doc-detective 4.32.0 → 4.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/dist/common/src/schemas/schemas.json +1288 -126
  2. package/dist/common/src/types/generated/record_v3.d.ts +21 -2
  3. package/dist/common/src/types/generated/record_v3.d.ts.map +1 -1
  4. package/dist/common/src/types/generated/step_v3.d.ts +21 -2
  5. package/dist/common/src/types/generated/step_v3.d.ts.map +1 -1
  6. package/dist/common/src/types/generated/test_v3.d.ts +42 -4
  7. package/dist/common/src/types/generated/test_v3.d.ts.map +1 -1
  8. package/dist/core/tests/ffmpegRecorder.d.ts.map +1 -1
  9. package/dist/core/tests/ffmpegRecorder.js +17 -2
  10. package/dist/core/tests/ffmpegRecorder.js.map +1 -1
  11. package/dist/core/tests/recordingCheckpoints.d.ts +76 -0
  12. package/dist/core/tests/recordingCheckpoints.d.ts.map +1 -0
  13. package/dist/core/tests/recordingCheckpoints.js +335 -0
  14. package/dist/core/tests/recordingCheckpoints.js.map +1 -0
  15. package/dist/core/tests/saveScreenshot.d.ts +5 -1
  16. package/dist/core/tests/saveScreenshot.d.ts.map +1 -1
  17. package/dist/core/tests/saveScreenshot.js +46 -12
  18. package/dist/core/tests/saveScreenshot.js.map +1 -1
  19. package/dist/core/tests/startRecording.d.ts.map +1 -1
  20. package/dist/core/tests/startRecording.js +26 -10
  21. package/dist/core/tests/startRecording.js.map +1 -1
  22. package/dist/core/tests/stopRecording.d.ts.map +1 -1
  23. package/dist/core/tests/stopRecording.js +283 -14
  24. package/dist/core/tests/stopRecording.js.map +1 -1
  25. package/dist/core/tests.d.ts.map +1 -1
  26. package/dist/core/tests.js +53 -37
  27. package/dist/core/tests.js.map +1 -1
  28. package/dist/hints/context.d.ts +1 -0
  29. package/dist/hints/context.d.ts.map +1 -1
  30. package/dist/hints/context.js +9 -0
  31. package/dist/hints/context.js.map +1 -1
  32. package/dist/hints/hints.d.ts.map +1 -1
  33. package/dist/hints/hints.js +15 -0
  34. package/dist/hints/hints.js.map +1 -1
  35. package/dist/hints/types.d.ts +8 -0
  36. package/dist/hints/types.d.ts.map +1 -1
  37. package/dist/index.cjs +1909 -325
  38. package/package.json +1 -1
package/dist/common/src/schemas/schemas.json CHANGED
@@ -30428,9 +30428,10 @@
30428
30428
  "anyOf": [
30429
30429
  {
30430
30430
  "title": "Screenshot (simple)",
30431
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
30431
30432
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
30432
30433
  "type": "string",
30433
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30434
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30434
30435
  "transform": [
30435
30436
  "trim"
30436
30437
  ]
@@ -30664,9 +30665,10 @@
30664
30665
  },
30665
30666
  "path": {
30666
30667
  "title": "Screenshot (simple)",
30668
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
30667
30669
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
30668
30670
  "type": "string",
30669
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30671
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30670
30672
  "transform": [
30671
30673
  "trim"
30672
30674
  ]
@@ -30924,9 +30926,10 @@
30924
30926
  "schemas": {
30925
30927
  "path": {
30926
30928
  "title": "Screenshot (simple)",
30929
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
30927
30930
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
30928
30931
  "type": "string",
30929
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30932
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30930
30933
  "transform": [
30931
30934
  "trim"
30932
30935
  ]
@@ -31160,9 +31163,10 @@
31160
31163
  },
31161
31164
  "path": {
31162
31165
  "title": "Screenshot (simple)",
31166
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
31163
31167
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
31164
31168
  "type": "string",
31165
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31169
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31166
31170
  "transform": [
31167
31171
  "trim"
31168
31172
  ]
@@ -31636,9 +31640,10 @@
31636
31640
  },
31637
31641
  "path": {
31638
31642
  "title": "Screenshot (simple)",
31643
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
31639
31644
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
31640
31645
  "type": "string",
31641
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31646
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31642
31647
  "transform": [
31643
31648
  "trim"
31644
31649
  ]
@@ -32020,6 +32025,7 @@
32020
32025
  "image.png",
32021
32026
  "static/images/image.png",
32022
32027
  "/User/manny/projects/doc-detective/static/images/image.png",
32028
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
32023
32029
  "https://example.com/static/images/image.png",
32024
32030
  {
32025
32031
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -34454,10 +34460,11 @@
34454
34460
  },
34455
34461
  "overwrite": {
34456
34462
  "type": "string",
34457
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
34463
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
34458
34464
  "enum": [
34459
34465
  "true",
34460
- "false"
34466
+ "false",
34467
+ "aboveVariation"
34461
34468
  ]
34462
34469
  },
34463
34470
  "name": {
@@ -34515,6 +34522,38 @@
34515
34522
  }
34516
34523
  }
34517
34524
  ]
34525
+ },
34526
+ "checkpoints": {
34527
+ "title": "Recording checkpoints",
34528
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
34529
+ "anyOf": [
34530
+ {
34531
+ "type": "boolean",
34532
+ "title": "Recording checkpoints (boolean)",
34533
+ "description": "If `true`, enables checkpoints with default settings."
34534
+ },
34535
+ {
34536
+ "type": "object",
34537
+ "title": "Recording checkpoints (detailed)",
34538
+ "additionalProperties": false,
34539
+ "properties": {
34540
+ "maxVariation": {
34541
+ "type": "number",
34542
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
34543
+ "default": 0.05,
34544
+ "minimum": 0,
34545
+ "maximum": 1
34546
+ },
34547
+ "directory": {
34548
+ "type": "string",
34549
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
34550
+ "transform": [
34551
+ "trim"
34552
+ ]
34553
+ }
34554
+ }
34555
+ }
34556
+ ]
34518
34557
  }
34519
34558
  },
34520
34559
  "title": "Record (detailed)"
@@ -34776,10 +34815,11 @@
34776
34815
  },
34777
34816
  "overwrite": {
34778
34817
  "type": "string",
34779
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
34818
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
34780
34819
  "enum": [
34781
34820
  "true",
34782
- "false"
34821
+ "false",
34822
+ "aboveVariation"
34783
34823
  ]
34784
34824
  },
34785
34825
  "name": {
@@ -34837,6 +34877,38 @@
34837
34877
  }
34838
34878
  }
34839
34879
  ]
34880
+ },
34881
+ "checkpoints": {
34882
+ "title": "Recording checkpoints",
34883
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
34884
+ "anyOf": [
34885
+ {
34886
+ "type": "boolean",
34887
+ "title": "Recording checkpoints (boolean)",
34888
+ "description": "If `true`, enables checkpoints with default settings."
34889
+ },
34890
+ {
34891
+ "type": "object",
34892
+ "title": "Recording checkpoints (detailed)",
34893
+ "additionalProperties": false,
34894
+ "properties": {
34895
+ "maxVariation": {
34896
+ "type": "number",
34897
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
34898
+ "default": 0.05,
34899
+ "minimum": 0,
34900
+ "maximum": 1
34901
+ },
34902
+ "directory": {
34903
+ "type": "string",
34904
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
34905
+ "transform": [
34906
+ "trim"
34907
+ ]
34908
+ }
34909
+ }
34910
+ }
34911
+ ]
34840
34912
  }
34841
34913
  },
34842
34914
  "title": "Record (detailed)"
@@ -34903,6 +34975,17 @@
34903
34975
  "path": "results.mp4",
34904
34976
  "engine": "ffmpeg"
34905
34977
  },
34978
+ {
34979
+ "path": "results.mp4",
34980
+ "checkpoints": true
34981
+ },
34982
+ {
34983
+ "path": "results.mp4",
34984
+ "checkpoints": {
34985
+ "maxVariation": 0.02,
34986
+ "directory": "baselines/results"
34987
+ }
34988
+ },
34906
34989
  {
34907
34990
  "path": "results.mp4",
34908
34991
  "engine": {
@@ -76067,9 +76150,10 @@
76067
76150
  "anyOf": [
76068
76151
  {
76069
76152
  "title": "Screenshot (simple)",
76153
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
76070
76154
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
76071
76155
  "type": "string",
76072
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76156
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76073
76157
  "transform": [
76074
76158
  "trim"
76075
76159
  ]
@@ -76303,9 +76387,10 @@
76303
76387
  },
76304
76388
  "path": {
76305
76389
  "title": "Screenshot (simple)",
76390
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
76306
76391
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
76307
76392
  "type": "string",
76308
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76393
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76309
76394
  "transform": [
76310
76395
  "trim"
76311
76396
  ]
@@ -76563,9 +76648,10 @@
76563
76648
  "schemas": {
76564
76649
  "path": {
76565
76650
  "title": "Screenshot (simple)",
76651
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
76566
76652
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
76567
76653
  "type": "string",
76568
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76654
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76569
76655
  "transform": [
76570
76656
  "trim"
76571
76657
  ]
@@ -76799,9 +76885,10 @@
76799
76885
  },
76800
76886
  "path": {
76801
76887
  "title": "Screenshot (simple)",
76888
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
76802
76889
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
76803
76890
  "type": "string",
76804
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76891
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76805
76892
  "transform": [
76806
76893
  "trim"
76807
76894
  ]
@@ -77275,9 +77362,10 @@
77275
77362
  },
77276
77363
  "path": {
77277
77364
  "title": "Screenshot (simple)",
77365
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
77278
77366
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
77279
77367
  "type": "string",
77280
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
77368
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
77281
77369
  "transform": [
77282
77370
  "trim"
77283
77371
  ]
@@ -77659,6 +77747,7 @@
77659
77747
  "image.png",
77660
77748
  "static/images/image.png",
77661
77749
  "/User/manny/projects/doc-detective/static/images/image.png",
77750
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
77662
77751
  "https://example.com/static/images/image.png",
77663
77752
  {
77664
77753
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -80093,10 +80182,11 @@
80093
80182
  },
80094
80183
  "overwrite": {
80095
80184
  "type": "string",
80096
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
80185
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
80097
80186
  "enum": [
80098
80187
  "true",
80099
- "false"
80188
+ "false",
80189
+ "aboveVariation"
80100
80190
  ]
80101
80191
  },
80102
80192
  "name": {
@@ -80154,6 +80244,38 @@
80154
80244
  }
80155
80245
  }
80156
80246
  ]
80247
+ },
80248
+ "checkpoints": {
80249
+ "title": "Recording checkpoints",
80250
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
80251
+ "anyOf": [
80252
+ {
80253
+ "type": "boolean",
80254
+ "title": "Recording checkpoints (boolean)",
80255
+ "description": "If `true`, enables checkpoints with default settings."
80256
+ },
80257
+ {
80258
+ "type": "object",
80259
+ "title": "Recording checkpoints (detailed)",
80260
+ "additionalProperties": false,
80261
+ "properties": {
80262
+ "maxVariation": {
80263
+ "type": "number",
80264
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
80265
+ "default": 0.05,
80266
+ "minimum": 0,
80267
+ "maximum": 1
80268
+ },
80269
+ "directory": {
80270
+ "type": "string",
80271
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
80272
+ "transform": [
80273
+ "trim"
80274
+ ]
80275
+ }
80276
+ }
80277
+ }
80278
+ ]
80157
80279
  }
80158
80280
  },
80159
80281
  "title": "Record (detailed)"
@@ -80415,10 +80537,11 @@
80415
80537
  },
80416
80538
  "overwrite": {
80417
80539
  "type": "string",
80418
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
80540
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
80419
80541
  "enum": [
80420
80542
  "true",
80421
- "false"
80543
+ "false",
80544
+ "aboveVariation"
80422
80545
  ]
80423
80546
  },
80424
80547
  "name": {
@@ -80476,6 +80599,38 @@
80476
80599
  }
80477
80600
  }
80478
80601
  ]
80602
+ },
80603
+ "checkpoints": {
80604
+ "title": "Recording checkpoints",
80605
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
80606
+ "anyOf": [
80607
+ {
80608
+ "type": "boolean",
80609
+ "title": "Recording checkpoints (boolean)",
80610
+ "description": "If `true`, enables checkpoints with default settings."
80611
+ },
80612
+ {
80613
+ "type": "object",
80614
+ "title": "Recording checkpoints (detailed)",
80615
+ "additionalProperties": false,
80616
+ "properties": {
80617
+ "maxVariation": {
80618
+ "type": "number",
80619
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
80620
+ "default": 0.05,
80621
+ "minimum": 0,
80622
+ "maximum": 1
80623
+ },
80624
+ "directory": {
80625
+ "type": "string",
80626
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
80627
+ "transform": [
80628
+ "trim"
80629
+ ]
80630
+ }
80631
+ }
80632
+ }
80633
+ ]
80479
80634
  }
80480
80635
  },
80481
80636
  "title": "Record (detailed)"
@@ -80542,6 +80697,17 @@
80542
80697
  "path": "results.mp4",
80543
80698
  "engine": "ffmpeg"
80544
80699
  },
80700
+ {
80701
+ "path": "results.mp4",
80702
+ "checkpoints": true
80703
+ },
80704
+ {
80705
+ "path": "results.mp4",
80706
+ "checkpoints": {
80707
+ "maxVariation": 0.02,
80708
+ "directory": "baselines/results"
80709
+ }
80710
+ },
80545
80711
  {
80546
80712
  "path": "results.mp4",
80547
80713
  "engine": {
@@ -106378,10 +106544,11 @@
106378
106544
  },
106379
106545
  "overwrite": {
106380
106546
  "type": "string",
106381
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
106547
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
106382
106548
  "enum": [
106383
106549
  "true",
106384
- "false"
106550
+ "false",
106551
+ "aboveVariation"
106385
106552
  ]
106386
106553
  },
106387
106554
  "name": {
@@ -106439,6 +106606,38 @@
106439
106606
  }
106440
106607
  }
106441
106608
  ]
106609
+ },
106610
+ "checkpoints": {
106611
+ "title": "Recording checkpoints",
106612
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
106613
+ "anyOf": [
106614
+ {
106615
+ "type": "boolean",
106616
+ "title": "Recording checkpoints (boolean)",
106617
+ "description": "If `true`, enables checkpoints with default settings."
106618
+ },
106619
+ {
106620
+ "type": "object",
106621
+ "title": "Recording checkpoints (detailed)",
106622
+ "additionalProperties": false,
106623
+ "properties": {
106624
+ "maxVariation": {
106625
+ "type": "number",
106626
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
106627
+ "default": 0.05,
106628
+ "minimum": 0,
106629
+ "maximum": 1
106630
+ },
106631
+ "directory": {
106632
+ "type": "string",
106633
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
106634
+ "transform": [
106635
+ "trim"
106636
+ ]
106637
+ }
106638
+ }
106639
+ }
106640
+ ]
106442
106641
  }
106443
106642
  },
106444
106643
  "title": "Record (detailed)"
@@ -106700,10 +106899,11 @@
106700
106899
  },
106701
106900
  "overwrite": {
106702
106901
  "type": "string",
106703
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
106902
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
106704
106903
  "enum": [
106705
106904
  "true",
106706
- "false"
106905
+ "false",
106906
+ "aboveVariation"
106707
106907
  ]
106708
106908
  },
106709
106909
  "name": {
@@ -106761,6 +106961,38 @@
106761
106961
  }
106762
106962
  }
106763
106963
  ]
106964
+ },
106965
+ "checkpoints": {
106966
+ "title": "Recording checkpoints",
106967
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
106968
+ "anyOf": [
106969
+ {
106970
+ "type": "boolean",
106971
+ "title": "Recording checkpoints (boolean)",
106972
+ "description": "If `true`, enables checkpoints with default settings."
106973
+ },
106974
+ {
106975
+ "type": "object",
106976
+ "title": "Recording checkpoints (detailed)",
106977
+ "additionalProperties": false,
106978
+ "properties": {
106979
+ "maxVariation": {
106980
+ "type": "number",
106981
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
106982
+ "default": 0.05,
106983
+ "minimum": 0,
106984
+ "maximum": 1
106985
+ },
106986
+ "directory": {
106987
+ "type": "string",
106988
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
106989
+ "transform": [
106990
+ "trim"
106991
+ ]
106992
+ }
106993
+ }
106994
+ }
106995
+ ]
106764
106996
  }
106765
106997
  },
106766
106998
  "title": "Record (detailed)"
@@ -106827,6 +107059,17 @@
106827
107059
  "path": "results.mp4",
106828
107060
  "engine": "ffmpeg"
106829
107061
  },
107062
+ {
107063
+ "path": "results.mp4",
107064
+ "checkpoints": true
107065
+ },
107066
+ {
107067
+ "path": "results.mp4",
107068
+ "checkpoints": {
107069
+ "maxVariation": 0.02,
107070
+ "directory": "baselines/results"
107071
+ }
107072
+ },
106830
107073
  {
106831
107074
  "path": "results.mp4",
106832
107075
  "engine": {
@@ -134993,9 +135236,10 @@
134993
135236
  "anyOf": [
134994
135237
  {
134995
135238
  "title": "Screenshot (simple)",
135239
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
134996
135240
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
134997
135241
  "type": "string",
134998
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135242
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
134999
135243
  "transform": [
135000
135244
  "trim"
135001
135245
  ]
@@ -135229,9 +135473,10 @@
135229
135473
  },
135230
135474
  "path": {
135231
135475
  "title": "Screenshot (simple)",
135476
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
135232
135477
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
135233
135478
  "type": "string",
135234
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135479
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135235
135480
  "transform": [
135236
135481
  "trim"
135237
135482
  ]
@@ -135489,9 +135734,10 @@
135489
135734
  "schemas": {
135490
135735
  "path": {
135491
135736
  "title": "Screenshot (simple)",
135737
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
135492
135738
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
135493
135739
  "type": "string",
135494
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135740
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135495
135741
  "transform": [
135496
135742
  "trim"
135497
135743
  ]
@@ -135725,9 +135971,10 @@
135725
135971
  },
135726
135972
  "path": {
135727
135973
  "title": "Screenshot (simple)",
135974
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
135728
135975
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
135729
135976
  "type": "string",
135730
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135977
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135731
135978
  "transform": [
135732
135979
  "trim"
135733
135980
  ]
@@ -136201,9 +136448,10 @@
136201
136448
  },
136202
136449
  "path": {
136203
136450
  "title": "Screenshot (simple)",
136451
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
136204
136452
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
136205
136453
  "type": "string",
136206
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
136454
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
136207
136455
  "transform": [
136208
136456
  "trim"
136209
136457
  ]
@@ -136585,6 +136833,7 @@
136585
136833
  "image.png",
136586
136834
  "static/images/image.png",
136587
136835
  "/User/manny/projects/doc-detective/static/images/image.png",
136836
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
136588
136837
  "https://example.com/static/images/image.png",
136589
136838
  {
136590
136839
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -139019,10 +139268,11 @@
139019
139268
  },
139020
139269
  "overwrite": {
139021
139270
  "type": "string",
139022
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
139271
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
139023
139272
  "enum": [
139024
139273
  "true",
139025
- "false"
139274
+ "false",
139275
+ "aboveVariation"
139026
139276
  ]
139027
139277
  },
139028
139278
  "name": {
@@ -139080,6 +139330,38 @@
139080
139330
  }
139081
139331
  }
139082
139332
  ]
139333
+ },
139334
+ "checkpoints": {
139335
+ "title": "Recording checkpoints",
139336
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
139337
+ "anyOf": [
139338
+ {
139339
+ "type": "boolean",
139340
+ "title": "Recording checkpoints (boolean)",
139341
+ "description": "If `true`, enables checkpoints with default settings."
139342
+ },
139343
+ {
139344
+ "type": "object",
139345
+ "title": "Recording checkpoints (detailed)",
139346
+ "additionalProperties": false,
139347
+ "properties": {
139348
+ "maxVariation": {
139349
+ "type": "number",
139350
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
139351
+ "default": 0.05,
139352
+ "minimum": 0,
139353
+ "maximum": 1
139354
+ },
139355
+ "directory": {
139356
+ "type": "string",
139357
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
139358
+ "transform": [
139359
+ "trim"
139360
+ ]
139361
+ }
139362
+ }
139363
+ }
139364
+ ]
139083
139365
  }
139084
139366
  },
139085
139367
  "title": "Record (detailed)"
@@ -139341,10 +139623,11 @@
139341
139623
  },
139342
139624
  "overwrite": {
139343
139625
  "type": "string",
139344
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
139626
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
139345
139627
  "enum": [
139346
139628
  "true",
139347
- "false"
139629
+ "false",
139630
+ "aboveVariation"
139348
139631
  ]
139349
139632
  },
139350
139633
  "name": {
@@ -139402,6 +139685,38 @@
139402
139685
  }
139403
139686
  }
139404
139687
  ]
139688
+ },
139689
+ "checkpoints": {
139690
+ "title": "Recording checkpoints",
139691
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
139692
+ "anyOf": [
139693
+ {
139694
+ "type": "boolean",
139695
+ "title": "Recording checkpoints (boolean)",
139696
+ "description": "If `true`, enables checkpoints with default settings."
139697
+ },
139698
+ {
139699
+ "type": "object",
139700
+ "title": "Recording checkpoints (detailed)",
139701
+ "additionalProperties": false,
139702
+ "properties": {
139703
+ "maxVariation": {
139704
+ "type": "number",
139705
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
139706
+ "default": 0.05,
139707
+ "minimum": 0,
139708
+ "maximum": 1
139709
+ },
139710
+ "directory": {
139711
+ "type": "string",
139712
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
139713
+ "transform": [
139714
+ "trim"
139715
+ ]
139716
+ }
139717
+ }
139718
+ }
139719
+ ]
139405
139720
  }
139406
139721
  },
139407
139722
  "title": "Record (detailed)"
@@ -139468,6 +139783,17 @@
139468
139783
  "path": "results.mp4",
139469
139784
  "engine": "ffmpeg"
139470
139785
  },
139786
+ {
139787
+ "path": "results.mp4",
139788
+ "checkpoints": true
139789
+ },
139790
+ {
139791
+ "path": "results.mp4",
139792
+ "checkpoints": {
139793
+ "maxVariation": 0.02,
139794
+ "directory": "baselines/results"
139795
+ }
139796
+ },
139471
139797
  {
139472
139798
  "path": "results.mp4",
139473
139799
  "engine": {
@@ -180632,9 +180958,10 @@
180632
180958
  "anyOf": [
180633
180959
  {
180634
180960
  "title": "Screenshot (simple)",
180961
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
180635
180962
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
180636
180963
  "type": "string",
180637
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
180964
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
180638
180965
  "transform": [
180639
180966
  "trim"
180640
180967
  ]
@@ -180868,9 +181195,10 @@
180868
181195
  },
180869
181196
  "path": {
180870
181197
  "title": "Screenshot (simple)",
181198
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
180871
181199
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
180872
181200
  "type": "string",
180873
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181201
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
180874
181202
  "transform": [
180875
181203
  "trim"
180876
181204
  ]
@@ -181128,9 +181456,10 @@
181128
181456
  "schemas": {
181129
181457
  "path": {
181130
181458
  "title": "Screenshot (simple)",
181459
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
181131
181460
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
181132
181461
  "type": "string",
181133
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181462
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181134
181463
  "transform": [
181135
181464
  "trim"
181136
181465
  ]
@@ -181364,9 +181693,10 @@
181364
181693
  },
181365
181694
  "path": {
181366
181695
  "title": "Screenshot (simple)",
181696
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
181367
181697
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
181368
181698
  "type": "string",
181369
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181699
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181370
181700
  "transform": [
181371
181701
  "trim"
181372
181702
  ]
@@ -181840,9 +182170,10 @@
181840
182170
  },
181841
182171
  "path": {
181842
182172
  "title": "Screenshot (simple)",
182173
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
181843
182174
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
181844
182175
  "type": "string",
181845
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
182176
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181846
182177
  "transform": [
181847
182178
  "trim"
181848
182179
  ]
@@ -182224,6 +182555,7 @@
182224
182555
  "image.png",
182225
182556
  "static/images/image.png",
182226
182557
  "/User/manny/projects/doc-detective/static/images/image.png",
182558
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
182227
182559
  "https://example.com/static/images/image.png",
182228
182560
  {
182229
182561
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -184658,10 +184990,11 @@
184658
184990
  },
184659
184991
  "overwrite": {
184660
184992
  "type": "string",
184661
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
184993
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
184662
184994
  "enum": [
184663
184995
  "true",
184664
- "false"
184996
+ "false",
184997
+ "aboveVariation"
184665
184998
  ]
184666
184999
  },
184667
185000
  "name": {
@@ -184719,6 +185052,38 @@
184719
185052
  }
184720
185053
  }
184721
185054
  ]
185055
+ },
185056
+ "checkpoints": {
185057
+ "title": "Recording checkpoints",
185058
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
185059
+ "anyOf": [
185060
+ {
185061
+ "type": "boolean",
185062
+ "title": "Recording checkpoints (boolean)",
185063
+ "description": "If `true`, enables checkpoints with default settings."
185064
+ },
185065
+ {
185066
+ "type": "object",
185067
+ "title": "Recording checkpoints (detailed)",
185068
+ "additionalProperties": false,
185069
+ "properties": {
185070
+ "maxVariation": {
185071
+ "type": "number",
185072
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
185073
+ "default": 0.05,
185074
+ "minimum": 0,
185075
+ "maximum": 1
185076
+ },
185077
+ "directory": {
185078
+ "type": "string",
185079
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
185080
+ "transform": [
185081
+ "trim"
185082
+ ]
185083
+ }
185084
+ }
185085
+ }
185086
+ ]
184722
185087
  }
184723
185088
  },
184724
185089
  "title": "Record (detailed)"
@@ -184980,10 +185345,11 @@
184980
185345
  },
184981
185346
  "overwrite": {
184982
185347
  "type": "string",
184983
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
185348
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
184984
185349
  "enum": [
184985
185350
  "true",
184986
- "false"
185351
+ "false",
185352
+ "aboveVariation"
184987
185353
  ]
184988
185354
  },
184989
185355
  "name": {
@@ -185041,6 +185407,38 @@
185041
185407
  }
185042
185408
  }
185043
185409
  ]
185410
+ },
185411
+ "checkpoints": {
185412
+ "title": "Recording checkpoints",
185413
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
185414
+ "anyOf": [
185415
+ {
185416
+ "type": "boolean",
185417
+ "title": "Recording checkpoints (boolean)",
185418
+ "description": "If `true`, enables checkpoints with default settings."
185419
+ },
185420
+ {
185421
+ "type": "object",
185422
+ "title": "Recording checkpoints (detailed)",
185423
+ "additionalProperties": false,
185424
+ "properties": {
185425
+ "maxVariation": {
185426
+ "type": "number",
185427
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
185428
+ "default": 0.05,
185429
+ "minimum": 0,
185430
+ "maximum": 1
185431
+ },
185432
+ "directory": {
185433
+ "type": "string",
185434
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
185435
+ "transform": [
185436
+ "trim"
185437
+ ]
185438
+ }
185439
+ }
185440
+ }
185441
+ ]
185044
185442
  }
185045
185443
  },
185046
185444
  "title": "Record (detailed)"
@@ -185107,6 +185505,17 @@
185107
185505
  "path": "results.mp4",
185108
185506
  "engine": "ffmpeg"
185109
185507
  },
185508
+ {
185509
+ "path": "results.mp4",
185510
+ "checkpoints": true
185511
+ },
185512
+ {
185513
+ "path": "results.mp4",
185514
+ "checkpoints": {
185515
+ "maxVariation": 0.02,
185516
+ "directory": "baselines/results"
185517
+ }
185518
+ },
185110
185519
  {
185111
185520
  "path": "results.mp4",
185112
185521
  "engine": {
@@ -228010,9 +228419,10 @@
228010
228419
  "anyOf": [
228011
228420
  {
228012
228421
  "title": "Screenshot (simple)",
228422
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
228013
228423
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
228014
228424
  "type": "string",
228015
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228425
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228016
228426
  "transform": [
228017
228427
  "trim"
228018
228428
  ]
@@ -228246,9 +228656,10 @@
228246
228656
  },
228247
228657
  "path": {
228248
228658
  "title": "Screenshot (simple)",
228659
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
228249
228660
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
228250
228661
  "type": "string",
228251
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228662
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228252
228663
  "transform": [
228253
228664
  "trim"
228254
228665
  ]
@@ -228506,9 +228917,10 @@
228506
228917
  "schemas": {
228507
228918
  "path": {
228508
228919
  "title": "Screenshot (simple)",
228920
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
228509
228921
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
228510
228922
  "type": "string",
228511
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228923
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228512
228924
  "transform": [
228513
228925
  "trim"
228514
228926
  ]
@@ -228742,9 +229154,10 @@
228742
229154
  },
228743
229155
  "path": {
228744
229156
  "title": "Screenshot (simple)",
229157
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
228745
229158
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
228746
229159
  "type": "string",
228747
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
229160
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228748
229161
  "transform": [
228749
229162
  "trim"
228750
229163
  ]
@@ -229218,9 +229631,10 @@
229218
229631
  },
229219
229632
  "path": {
229220
229633
  "title": "Screenshot (simple)",
229634
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
229221
229635
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
229222
229636
  "type": "string",
229223
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
229637
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
229224
229638
  "transform": [
229225
229639
  "trim"
229226
229640
  ]
@@ -229602,6 +230016,7 @@
229602
230016
  "image.png",
229603
230017
  "static/images/image.png",
229604
230018
  "/User/manny/projects/doc-detective/static/images/image.png",
230019
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
229605
230020
  "https://example.com/static/images/image.png",
229606
230021
  {
229607
230022
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -232036,10 +232451,11 @@
232036
232451
  },
232037
232452
  "overwrite": {
232038
232453
  "type": "string",
232039
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
232454
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
232040
232455
  "enum": [
232041
232456
  "true",
232042
- "false"
232457
+ "false",
232458
+ "aboveVariation"
232043
232459
  ]
232044
232460
  },
232045
232461
  "name": {
@@ -232097,6 +232513,38 @@
232097
232513
  }
232098
232514
  }
232099
232515
  ]
232516
+ },
232517
+ "checkpoints": {
232518
+ "title": "Recording checkpoints",
232519
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
232520
+ "anyOf": [
232521
+ {
232522
+ "type": "boolean",
232523
+ "title": "Recording checkpoints (boolean)",
232524
+ "description": "If `true`, enables checkpoints with default settings."
232525
+ },
232526
+ {
232527
+ "type": "object",
232528
+ "title": "Recording checkpoints (detailed)",
232529
+ "additionalProperties": false,
232530
+ "properties": {
232531
+ "maxVariation": {
232532
+ "type": "number",
232533
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
232534
+ "default": 0.05,
232535
+ "minimum": 0,
232536
+ "maximum": 1
232537
+ },
232538
+ "directory": {
232539
+ "type": "string",
232540
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
232541
+ "transform": [
232542
+ "trim"
232543
+ ]
232544
+ }
232545
+ }
232546
+ }
232547
+ ]
232100
232548
  }
232101
232549
  },
232102
232550
  "title": "Record (detailed)"
@@ -232358,10 +232806,11 @@
232358
232806
  },
232359
232807
  "overwrite": {
232360
232808
  "type": "string",
232361
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
232809
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
232362
232810
  "enum": [
232363
232811
  "true",
232364
- "false"
232812
+ "false",
232813
+ "aboveVariation"
232365
232814
  ]
232366
232815
  },
232367
232816
  "name": {
@@ -232419,6 +232868,38 @@
232419
232868
  }
232420
232869
  }
232421
232870
  ]
232871
+ },
232872
+ "checkpoints": {
232873
+ "title": "Recording checkpoints",
232874
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
232875
+ "anyOf": [
232876
+ {
232877
+ "type": "boolean",
232878
+ "title": "Recording checkpoints (boolean)",
232879
+ "description": "If `true`, enables checkpoints with default settings."
232880
+ },
232881
+ {
232882
+ "type": "object",
232883
+ "title": "Recording checkpoints (detailed)",
232884
+ "additionalProperties": false,
232885
+ "properties": {
232886
+ "maxVariation": {
232887
+ "type": "number",
232888
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
232889
+ "default": 0.05,
232890
+ "minimum": 0,
232891
+ "maximum": 1
232892
+ },
232893
+ "directory": {
232894
+ "type": "string",
232895
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
232896
+ "transform": [
232897
+ "trim"
232898
+ ]
232899
+ }
232900
+ }
232901
+ }
232902
+ ]
232422
232903
  }
232423
232904
  },
232424
232905
  "title": "Record (detailed)"
@@ -232485,6 +232966,17 @@
232485
232966
  "path": "results.mp4",
232486
232967
  "engine": "ffmpeg"
232487
232968
  },
232969
+ {
232970
+ "path": "results.mp4",
232971
+ "checkpoints": true
232972
+ },
232973
+ {
232974
+ "path": "results.mp4",
232975
+ "checkpoints": {
232976
+ "maxVariation": 0.02,
232977
+ "directory": "baselines/results"
232978
+ }
232979
+ },
232488
232980
  {
232489
232981
  "path": "results.mp4",
232490
232982
  "engine": {
@@ -272911,9 +273403,10 @@
272911
273403
  "anyOf": [
272912
273404
  {
272913
273405
  "title": "Screenshot (simple)",
273406
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
272914
273407
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
272915
273408
  "type": "string",
272916
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273409
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
272917
273410
  "transform": [
272918
273411
  "trim"
272919
273412
  ]
@@ -273147,9 +273640,10 @@
273147
273640
  },
273148
273641
  "path": {
273149
273642
  "title": "Screenshot (simple)",
273643
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
273150
273644
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
273151
273645
  "type": "string",
273152
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273646
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273153
273647
  "transform": [
273154
273648
  "trim"
273155
273649
  ]
@@ -273407,9 +273901,10 @@
273407
273901
  "schemas": {
273408
273902
  "path": {
273409
273903
  "title": "Screenshot (simple)",
273904
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
273410
273905
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
273411
273906
  "type": "string",
273412
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273907
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273413
273908
  "transform": [
273414
273909
  "trim"
273415
273910
  ]
@@ -273643,9 +274138,10 @@
273643
274138
  },
273644
274139
  "path": {
273645
274140
  "title": "Screenshot (simple)",
274141
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
273646
274142
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
273647
274143
  "type": "string",
273648
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
274144
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273649
274145
  "transform": [
273650
274146
  "trim"
273651
274147
  ]
@@ -274119,9 +274615,10 @@
274119
274615
  },
274120
274616
  "path": {
274121
274617
  "title": "Screenshot (simple)",
274618
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
274122
274619
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
274123
274620
  "type": "string",
274124
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
274621
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
274125
274622
  "transform": [
274126
274623
  "trim"
274127
274624
  ]
@@ -274503,6 +275000,7 @@
274503
275000
  "image.png",
274504
275001
  "static/images/image.png",
274505
275002
  "/User/manny/projects/doc-detective/static/images/image.png",
275003
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
274506
275004
  "https://example.com/static/images/image.png",
274507
275005
  {
274508
275006
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -276937,10 +277435,11 @@
276937
277435
  },
276938
277436
  "overwrite": {
276939
277437
  "type": "string",
276940
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
277438
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
276941
277439
  "enum": [
276942
277440
  "true",
276943
- "false"
277441
+ "false",
277442
+ "aboveVariation"
276944
277443
  ]
276945
277444
  },
276946
277445
  "name": {
@@ -276998,6 +277497,38 @@
276998
277497
  }
276999
277498
  }
277000
277499
  ]
277500
+ },
277501
+ "checkpoints": {
277502
+ "title": "Recording checkpoints",
277503
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
277504
+ "anyOf": [
277505
+ {
277506
+ "type": "boolean",
277507
+ "title": "Recording checkpoints (boolean)",
277508
+ "description": "If `true`, enables checkpoints with default settings."
277509
+ },
277510
+ {
277511
+ "type": "object",
277512
+ "title": "Recording checkpoints (detailed)",
277513
+ "additionalProperties": false,
277514
+ "properties": {
277515
+ "maxVariation": {
277516
+ "type": "number",
277517
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
277518
+ "default": 0.05,
277519
+ "minimum": 0,
277520
+ "maximum": 1
277521
+ },
277522
+ "directory": {
277523
+ "type": "string",
277524
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
277525
+ "transform": [
277526
+ "trim"
277527
+ ]
277528
+ }
277529
+ }
277530
+ }
277531
+ ]
277001
277532
  }
277002
277533
  },
277003
277534
  "title": "Record (detailed)"
@@ -277259,10 +277790,11 @@
277259
277790
  },
277260
277791
  "overwrite": {
277261
277792
  "type": "string",
277262
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
277793
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
277263
277794
  "enum": [
277264
277795
  "true",
277265
- "false"
277796
+ "false",
277797
+ "aboveVariation"
277266
277798
  ]
277267
277799
  },
277268
277800
  "name": {
@@ -277320,6 +277852,38 @@
277320
277852
  }
277321
277853
  }
277322
277854
  ]
277855
+ },
277856
+ "checkpoints": {
277857
+ "title": "Recording checkpoints",
277858
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
277859
+ "anyOf": [
277860
+ {
277861
+ "type": "boolean",
277862
+ "title": "Recording checkpoints (boolean)",
277863
+ "description": "If `true`, enables checkpoints with default settings."
277864
+ },
277865
+ {
277866
+ "type": "object",
277867
+ "title": "Recording checkpoints (detailed)",
277868
+ "additionalProperties": false,
277869
+ "properties": {
277870
+ "maxVariation": {
277871
+ "type": "number",
277872
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
277873
+ "default": 0.05,
277874
+ "minimum": 0,
277875
+ "maximum": 1
277876
+ },
277877
+ "directory": {
277878
+ "type": "string",
277879
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
277880
+ "transform": [
277881
+ "trim"
277882
+ ]
277883
+ }
277884
+ }
277885
+ }
277886
+ ]
277323
277887
  }
277324
277888
  },
277325
277889
  "title": "Record (detailed)"
@@ -277386,6 +277950,17 @@
277386
277950
  "path": "results.mp4",
277387
277951
  "engine": "ffmpeg"
277388
277952
  },
277953
+ {
277954
+ "path": "results.mp4",
277955
+ "checkpoints": true
277956
+ },
277957
+ {
277958
+ "path": "results.mp4",
277959
+ "checkpoints": {
277960
+ "maxVariation": 0.02,
277961
+ "directory": "baselines/results"
277962
+ }
277963
+ },
277389
277964
  {
277390
277965
  "path": "results.mp4",
277391
277966
  "engine": {
@@ -320773,9 +321348,10 @@
320773
321348
  "anyOf": [
320774
321349
  {
320775
321350
  "title": "Screenshot (simple)",
321351
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
320776
321352
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
320777
321353
  "type": "string",
320778
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321354
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
320779
321355
  "transform": [
320780
321356
  "trim"
320781
321357
  ]
@@ -321009,9 +321585,10 @@
321009
321585
  },
321010
321586
  "path": {
321011
321587
  "title": "Screenshot (simple)",
321588
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
321012
321589
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
321013
321590
  "type": "string",
321014
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321591
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321015
321592
  "transform": [
321016
321593
  "trim"
321017
321594
  ]
@@ -321269,9 +321846,10 @@
321269
321846
  "schemas": {
321270
321847
  "path": {
321271
321848
  "title": "Screenshot (simple)",
321849
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
321272
321850
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
321273
321851
  "type": "string",
321274
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321852
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321275
321853
  "transform": [
321276
321854
  "trim"
321277
321855
  ]
@@ -321505,9 +322083,10 @@
321505
322083
  },
321506
322084
  "path": {
321507
322085
  "title": "Screenshot (simple)",
322086
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
321508
322087
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
321509
322088
  "type": "string",
321510
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
322089
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321511
322090
  "transform": [
321512
322091
  "trim"
321513
322092
  ]
@@ -321981,9 +322560,10 @@
321981
322560
  },
321982
322561
  "path": {
321983
322562
  "title": "Screenshot (simple)",
322563
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
321984
322564
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
321985
322565
  "type": "string",
321986
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
322566
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321987
322567
  "transform": [
321988
322568
  "trim"
321989
322569
  ]
@@ -322365,6 +322945,7 @@
322365
322945
  "image.png",
322366
322946
  "static/images/image.png",
322367
322947
  "/User/manny/projects/doc-detective/static/images/image.png",
322948
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
322368
322949
  "https://example.com/static/images/image.png",
322369
322950
  {
322370
322951
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -324799,10 +325380,11 @@
324799
325380
  },
324800
325381
  "overwrite": {
324801
325382
  "type": "string",
324802
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
325383
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
324803
325384
  "enum": [
324804
325385
  "true",
324805
- "false"
325386
+ "false",
325387
+ "aboveVariation"
324806
325388
  ]
324807
325389
  },
324808
325390
  "name": {
@@ -324860,6 +325442,38 @@
324860
325442
  }
324861
325443
  }
324862
325444
  ]
325445
+ },
325446
+ "checkpoints": {
325447
+ "title": "Recording checkpoints",
325448
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
325449
+ "anyOf": [
325450
+ {
325451
+ "type": "boolean",
325452
+ "title": "Recording checkpoints (boolean)",
325453
+ "description": "If `true`, enables checkpoints with default settings."
325454
+ },
325455
+ {
325456
+ "type": "object",
325457
+ "title": "Recording checkpoints (detailed)",
325458
+ "additionalProperties": false,
325459
+ "properties": {
325460
+ "maxVariation": {
325461
+ "type": "number",
325462
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
325463
+ "default": 0.05,
325464
+ "minimum": 0,
325465
+ "maximum": 1
325466
+ },
325467
+ "directory": {
325468
+ "type": "string",
325469
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
325470
+ "transform": [
325471
+ "trim"
325472
+ ]
325473
+ }
325474
+ }
325475
+ }
325476
+ ]
324863
325477
  }
324864
325478
  },
324865
325479
  "title": "Record (detailed)"
@@ -325121,10 +325735,11 @@
325121
325735
  },
325122
325736
  "overwrite": {
325123
325737
  "type": "string",
325124
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
325738
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
325125
325739
  "enum": [
325126
325740
  "true",
325127
- "false"
325741
+ "false",
325742
+ "aboveVariation"
325128
325743
  ]
325129
325744
  },
325130
325745
  "name": {
@@ -325182,6 +325797,38 @@
325182
325797
  }
325183
325798
  }
325184
325799
  ]
325800
+ },
325801
+ "checkpoints": {
325802
+ "title": "Recording checkpoints",
325803
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
325804
+ "anyOf": [
325805
+ {
325806
+ "type": "boolean",
325807
+ "title": "Recording checkpoints (boolean)",
325808
+ "description": "If `true`, enables checkpoints with default settings."
325809
+ },
325810
+ {
325811
+ "type": "object",
325812
+ "title": "Recording checkpoints (detailed)",
325813
+ "additionalProperties": false,
325814
+ "properties": {
325815
+ "maxVariation": {
325816
+ "type": "number",
325817
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
325818
+ "default": 0.05,
325819
+ "minimum": 0,
325820
+ "maximum": 1
325821
+ },
325822
+ "directory": {
325823
+ "type": "string",
325824
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
325825
+ "transform": [
325826
+ "trim"
325827
+ ]
325828
+ }
325829
+ }
325830
+ }
325831
+ ]
325185
325832
  }
325186
325833
  },
325187
325834
  "title": "Record (detailed)"
@@ -325248,6 +325895,17 @@
325248
325895
  "path": "results.mp4",
325249
325896
  "engine": "ffmpeg"
325250
325897
  },
325898
+ {
325899
+ "path": "results.mp4",
325900
+ "checkpoints": true
325901
+ },
325902
+ {
325903
+ "path": "results.mp4",
325904
+ "checkpoints": {
325905
+ "maxVariation": 0.02,
325906
+ "directory": "baselines/results"
325907
+ }
325908
+ },
325251
325909
  {
325252
325910
  "path": "results.mp4",
325253
325911
  "engine": {
@@ -365674,9 +366332,10 @@
365674
366332
  "anyOf": [
365675
366333
  {
365676
366334
  "title": "Screenshot (simple)",
366335
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
365677
366336
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
365678
366337
  "type": "string",
365679
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366338
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
365680
366339
  "transform": [
365681
366340
  "trim"
365682
366341
  ]
@@ -365910,9 +366569,10 @@
365910
366569
  },
365911
366570
  "path": {
365912
366571
  "title": "Screenshot (simple)",
366572
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
365913
366573
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
365914
366574
  "type": "string",
365915
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366575
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
365916
366576
  "transform": [
365917
366577
  "trim"
365918
366578
  ]
@@ -366170,9 +366830,10 @@
366170
366830
  "schemas": {
366171
366831
  "path": {
366172
366832
  "title": "Screenshot (simple)",
366833
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
366173
366834
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
366174
366835
  "type": "string",
366175
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366836
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366176
366837
  "transform": [
366177
366838
  "trim"
366178
366839
  ]
@@ -366406,9 +367067,10 @@
366406
367067
  },
366407
367068
  "path": {
366408
367069
  "title": "Screenshot (simple)",
367070
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
366409
367071
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
366410
367072
  "type": "string",
366411
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
367073
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366412
367074
  "transform": [
366413
367075
  "trim"
366414
367076
  ]
@@ -366882,9 +367544,10 @@
366882
367544
  },
366883
367545
  "path": {
366884
367546
  "title": "Screenshot (simple)",
367547
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
366885
367548
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
366886
367549
  "type": "string",
366887
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
367550
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366888
367551
  "transform": [
366889
367552
  "trim"
366890
367553
  ]
@@ -367266,6 +367929,7 @@
367266
367929
  "image.png",
367267
367930
  "static/images/image.png",
367268
367931
  "/User/manny/projects/doc-detective/static/images/image.png",
367932
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
367269
367933
  "https://example.com/static/images/image.png",
367270
367934
  {
367271
367935
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -369700,10 +370364,11 @@
369700
370364
  },
369701
370365
  "overwrite": {
369702
370366
  "type": "string",
369703
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
370367
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
369704
370368
  "enum": [
369705
370369
  "true",
369706
- "false"
370370
+ "false",
370371
+ "aboveVariation"
369707
370372
  ]
369708
370373
  },
369709
370374
  "name": {
@@ -369761,6 +370426,38 @@
369761
370426
  }
369762
370427
  }
369763
370428
  ]
370429
+ },
370430
+ "checkpoints": {
370431
+ "title": "Recording checkpoints",
370432
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
370433
+ "anyOf": [
370434
+ {
370435
+ "type": "boolean",
370436
+ "title": "Recording checkpoints (boolean)",
370437
+ "description": "If `true`, enables checkpoints with default settings."
370438
+ },
370439
+ {
370440
+ "type": "object",
370441
+ "title": "Recording checkpoints (detailed)",
370442
+ "additionalProperties": false,
370443
+ "properties": {
370444
+ "maxVariation": {
370445
+ "type": "number",
370446
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
370447
+ "default": 0.05,
370448
+ "minimum": 0,
370449
+ "maximum": 1
370450
+ },
370451
+ "directory": {
370452
+ "type": "string",
370453
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
370454
+ "transform": [
370455
+ "trim"
370456
+ ]
370457
+ }
370458
+ }
370459
+ }
370460
+ ]
369764
370461
  }
369765
370462
  },
369766
370463
  "title": "Record (detailed)"
@@ -370022,10 +370719,11 @@
370022
370719
  },
370023
370720
  "overwrite": {
370024
370721
  "type": "string",
370025
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
370722
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
370026
370723
  "enum": [
370027
370724
  "true",
370028
- "false"
370725
+ "false",
370726
+ "aboveVariation"
370029
370727
  ]
370030
370728
  },
370031
370729
  "name": {
@@ -370083,6 +370781,38 @@
370083
370781
  }
370084
370782
  }
370085
370783
  ]
370784
+ },
370785
+ "checkpoints": {
370786
+ "title": "Recording checkpoints",
370787
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
370788
+ "anyOf": [
370789
+ {
370790
+ "type": "boolean",
370791
+ "title": "Recording checkpoints (boolean)",
370792
+ "description": "If `true`, enables checkpoints with default settings."
370793
+ },
370794
+ {
370795
+ "type": "object",
370796
+ "title": "Recording checkpoints (detailed)",
370797
+ "additionalProperties": false,
370798
+ "properties": {
370799
+ "maxVariation": {
370800
+ "type": "number",
370801
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
370802
+ "default": 0.05,
370803
+ "minimum": 0,
370804
+ "maximum": 1
370805
+ },
370806
+ "directory": {
370807
+ "type": "string",
370808
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
370809
+ "transform": [
370810
+ "trim"
370811
+ ]
370812
+ }
370813
+ }
370814
+ }
370815
+ ]
370086
370816
  }
370087
370817
  },
370088
370818
  "title": "Record (detailed)"
@@ -370149,6 +370879,17 @@
370149
370879
  "path": "results.mp4",
370150
370880
  "engine": "ffmpeg"
370151
370881
  },
370882
+ {
370883
+ "path": "results.mp4",
370884
+ "checkpoints": true
370885
+ },
370886
+ {
370887
+ "path": "results.mp4",
370888
+ "checkpoints": {
370889
+ "maxVariation": 0.02,
370890
+ "directory": "baselines/results"
370891
+ }
370892
+ },
370152
370893
  {
370153
370894
  "path": "results.mp4",
370154
370895
  "engine": {
@@ -385685,9 +386426,10 @@
385685
386426
  "anyOf": [
385686
386427
  {
385687
386428
  "title": "Screenshot (simple)",
386429
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
385688
386430
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
385689
386431
  "type": "string",
385690
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386432
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
385691
386433
  "transform": [
385692
386434
  "trim"
385693
386435
  ]
@@ -385921,9 +386663,10 @@
385921
386663
  },
385922
386664
  "path": {
385923
386665
  "title": "Screenshot (simple)",
386666
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
385924
386667
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
385925
386668
  "type": "string",
385926
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386669
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
385927
386670
  "transform": [
385928
386671
  "trim"
385929
386672
  ]
@@ -386181,9 +386924,10 @@
386181
386924
  "schemas": {
386182
386925
  "path": {
386183
386926
  "title": "Screenshot (simple)",
386927
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
386184
386928
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
386185
386929
  "type": "string",
386186
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386930
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386187
386931
  "transform": [
386188
386932
  "trim"
386189
386933
  ]
@@ -386417,9 +387161,10 @@
386417
387161
  },
386418
387162
  "path": {
386419
387163
  "title": "Screenshot (simple)",
387164
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
386420
387165
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
386421
387166
  "type": "string",
386422
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
387167
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386423
387168
  "transform": [
386424
387169
  "trim"
386425
387170
  ]
@@ -386893,9 +387638,10 @@
386893
387638
  },
386894
387639
  "path": {
386895
387640
  "title": "Screenshot (simple)",
387641
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
386896
387642
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
386897
387643
  "type": "string",
386898
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
387644
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386899
387645
  "transform": [
386900
387646
  "trim"
386901
387647
  ]
@@ -387277,6 +388023,7 @@
387277
388023
  "image.png",
387278
388024
  "static/images/image.png",
387279
388025
  "/User/manny/projects/doc-detective/static/images/image.png",
388026
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
387280
388027
  "https://example.com/static/images/image.png",
387281
388028
  {
387282
388029
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -416860,9 +417607,10 @@
416860
417607
  "anyOf": [
416861
417608
  {
416862
417609
  "title": "Screenshot (simple)",
417610
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
416863
417611
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
416864
417612
  "type": "string",
416865
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417613
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
416866
417614
  "transform": [
416867
417615
  "trim"
416868
417616
  ]
@@ -417096,9 +417844,10 @@
417096
417844
  },
417097
417845
  "path": {
417098
417846
  "title": "Screenshot (simple)",
417847
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
417099
417848
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
417100
417849
  "type": "string",
417101
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417850
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417102
417851
  "transform": [
417103
417852
  "trim"
417104
417853
  ]
@@ -417356,9 +418105,10 @@
417356
418105
  "schemas": {
417357
418106
  "path": {
417358
418107
  "title": "Screenshot (simple)",
418108
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
417359
418109
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
417360
418110
  "type": "string",
417361
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418111
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417362
418112
  "transform": [
417363
418113
  "trim"
417364
418114
  ]
@@ -417592,9 +418342,10 @@
417592
418342
  },
417593
418343
  "path": {
417594
418344
  "title": "Screenshot (simple)",
418345
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
417595
418346
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
417596
418347
  "type": "string",
417597
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418348
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417598
418349
  "transform": [
417599
418350
  "trim"
417600
418351
  ]
@@ -418068,9 +418819,10 @@
418068
418819
  },
418069
418820
  "path": {
418070
418821
  "title": "Screenshot (simple)",
418822
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
418071
418823
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
418072
418824
  "type": "string",
418073
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418825
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418074
418826
  "transform": [
418075
418827
  "trim"
418076
418828
  ]
@@ -418452,6 +419204,7 @@
418452
419204
  "image.png",
418453
419205
  "static/images/image.png",
418454
419206
  "/User/manny/projects/doc-detective/static/images/image.png",
419207
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
418455
419208
  "https://example.com/static/images/image.png",
418456
419209
  {
418457
419210
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -420886,10 +421639,11 @@
420886
421639
  },
420887
421640
  "overwrite": {
420888
421641
  "type": "string",
420889
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
421642
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
420890
421643
  "enum": [
420891
421644
  "true",
420892
- "false"
421645
+ "false",
421646
+ "aboveVariation"
420893
421647
  ]
420894
421648
  },
420895
421649
  "name": {
@@ -420947,6 +421701,38 @@
420947
421701
  }
420948
421702
  }
420949
421703
  ]
421704
+ },
421705
+ "checkpoints": {
421706
+ "title": "Recording checkpoints",
421707
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
421708
+ "anyOf": [
421709
+ {
421710
+ "type": "boolean",
421711
+ "title": "Recording checkpoints (boolean)",
421712
+ "description": "If `true`, enables checkpoints with default settings."
421713
+ },
421714
+ {
421715
+ "type": "object",
421716
+ "title": "Recording checkpoints (detailed)",
421717
+ "additionalProperties": false,
421718
+ "properties": {
421719
+ "maxVariation": {
421720
+ "type": "number",
421721
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
421722
+ "default": 0.05,
421723
+ "minimum": 0,
421724
+ "maximum": 1
421725
+ },
421726
+ "directory": {
421727
+ "type": "string",
421728
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
421729
+ "transform": [
421730
+ "trim"
421731
+ ]
421732
+ }
421733
+ }
421734
+ }
421735
+ ]
420950
421736
  }
420951
421737
  },
420952
421738
  "title": "Record (detailed)"
@@ -421208,10 +421994,11 @@
421208
421994
  },
421209
421995
  "overwrite": {
421210
421996
  "type": "string",
421211
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
421997
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
421212
421998
  "enum": [
421213
421999
  "true",
421214
- "false"
422000
+ "false",
422001
+ "aboveVariation"
421215
422002
  ]
421216
422003
  },
421217
422004
  "name": {
@@ -421269,6 +422056,38 @@
421269
422056
  }
421270
422057
  }
421271
422058
  ]
422059
+ },
422060
+ "checkpoints": {
422061
+ "title": "Recording checkpoints",
422062
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
422063
+ "anyOf": [
422064
+ {
422065
+ "type": "boolean",
422066
+ "title": "Recording checkpoints (boolean)",
422067
+ "description": "If `true`, enables checkpoints with default settings."
422068
+ },
422069
+ {
422070
+ "type": "object",
422071
+ "title": "Recording checkpoints (detailed)",
422072
+ "additionalProperties": false,
422073
+ "properties": {
422074
+ "maxVariation": {
422075
+ "type": "number",
422076
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
422077
+ "default": 0.05,
422078
+ "minimum": 0,
422079
+ "maximum": 1
422080
+ },
422081
+ "directory": {
422082
+ "type": "string",
422083
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
422084
+ "transform": [
422085
+ "trim"
422086
+ ]
422087
+ }
422088
+ }
422089
+ }
422090
+ ]
421272
422091
  }
421273
422092
  },
421274
422093
  "title": "Record (detailed)"
@@ -421335,6 +422154,17 @@
421335
422154
  "path": "results.mp4",
421336
422155
  "engine": "ffmpeg"
421337
422156
  },
422157
+ {
422158
+ "path": "results.mp4",
422159
+ "checkpoints": true
422160
+ },
422161
+ {
422162
+ "path": "results.mp4",
422163
+ "checkpoints": {
422164
+ "maxVariation": 0.02,
422165
+ "directory": "baselines/results"
422166
+ }
422167
+ },
421338
422168
  {
421339
422169
  "path": "results.mp4",
421340
422170
  "engine": {
@@ -461761,9 +462591,10 @@
461761
462591
  "anyOf": [
461762
462592
  {
461763
462593
  "title": "Screenshot (simple)",
462594
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
461764
462595
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
461765
462596
  "type": "string",
461766
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462597
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
461767
462598
  "transform": [
461768
462599
  "trim"
461769
462600
  ]
@@ -461997,9 +462828,10 @@
461997
462828
  },
461998
462829
  "path": {
461999
462830
  "title": "Screenshot (simple)",
462831
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
462000
462832
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
462001
462833
  "type": "string",
462002
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462834
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462003
462835
  "transform": [
462004
462836
  "trim"
462005
462837
  ]
@@ -462257,9 +463089,10 @@
462257
463089
  "schemas": {
462258
463090
  "path": {
462259
463091
  "title": "Screenshot (simple)",
463092
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
462260
463093
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
462261
463094
  "type": "string",
462262
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463095
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462263
463096
  "transform": [
462264
463097
  "trim"
462265
463098
  ]
@@ -462493,9 +463326,10 @@
462493
463326
  },
462494
463327
  "path": {
462495
463328
  "title": "Screenshot (simple)",
463329
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
462496
463330
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
462497
463331
  "type": "string",
462498
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463332
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462499
463333
  "transform": [
462500
463334
  "trim"
462501
463335
  ]
@@ -462969,9 +463803,10 @@
462969
463803
  },
462970
463804
  "path": {
462971
463805
  "title": "Screenshot (simple)",
463806
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
462972
463807
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
462973
463808
  "type": "string",
462974
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463809
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462975
463810
  "transform": [
462976
463811
  "trim"
462977
463812
  ]
@@ -463353,6 +464188,7 @@
463353
464188
  "image.png",
463354
464189
  "static/images/image.png",
463355
464190
  "/User/manny/projects/doc-detective/static/images/image.png",
464191
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
463356
464192
  "https://example.com/static/images/image.png",
463357
464193
  {
463358
464194
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -465787,10 +466623,11 @@
465787
466623
  },
465788
466624
  "overwrite": {
465789
466625
  "type": "string",
465790
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
466626
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
465791
466627
  "enum": [
465792
466628
  "true",
465793
- "false"
466629
+ "false",
466630
+ "aboveVariation"
465794
466631
  ]
465795
466632
  },
465796
466633
  "name": {
@@ -465848,6 +466685,38 @@
465848
466685
  }
465849
466686
  }
465850
466687
  ]
466688
+ },
466689
+ "checkpoints": {
466690
+ "title": "Recording checkpoints",
466691
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
466692
+ "anyOf": [
466693
+ {
466694
+ "type": "boolean",
466695
+ "title": "Recording checkpoints (boolean)",
466696
+ "description": "If `true`, enables checkpoints with default settings."
466697
+ },
466698
+ {
466699
+ "type": "object",
466700
+ "title": "Recording checkpoints (detailed)",
466701
+ "additionalProperties": false,
466702
+ "properties": {
466703
+ "maxVariation": {
466704
+ "type": "number",
466705
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
466706
+ "default": 0.05,
466707
+ "minimum": 0,
466708
+ "maximum": 1
466709
+ },
466710
+ "directory": {
466711
+ "type": "string",
466712
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
466713
+ "transform": [
466714
+ "trim"
466715
+ ]
466716
+ }
466717
+ }
466718
+ }
466719
+ ]
465851
466720
  }
465852
466721
  },
465853
466722
  "title": "Record (detailed)"
@@ -466109,10 +466978,11 @@
466109
466978
  },
466110
466979
  "overwrite": {
466111
466980
  "type": "string",
466112
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
466981
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
466113
466982
  "enum": [
466114
466983
  "true",
466115
- "false"
466984
+ "false",
466985
+ "aboveVariation"
466116
466986
  ]
466117
466987
  },
466118
466988
  "name": {
@@ -466170,6 +467040,38 @@
466170
467040
  }
466171
467041
  }
466172
467042
  ]
467043
+ },
467044
+ "checkpoints": {
467045
+ "title": "Recording checkpoints",
467046
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
467047
+ "anyOf": [
467048
+ {
467049
+ "type": "boolean",
467050
+ "title": "Recording checkpoints (boolean)",
467051
+ "description": "If `true`, enables checkpoints with default settings."
467052
+ },
467053
+ {
467054
+ "type": "object",
467055
+ "title": "Recording checkpoints (detailed)",
467056
+ "additionalProperties": false,
467057
+ "properties": {
467058
+ "maxVariation": {
467059
+ "type": "number",
467060
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
467061
+ "default": 0.05,
467062
+ "minimum": 0,
467063
+ "maximum": 1
467064
+ },
467065
+ "directory": {
467066
+ "type": "string",
467067
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
467068
+ "transform": [
467069
+ "trim"
467070
+ ]
467071
+ }
467072
+ }
467073
+ }
467074
+ ]
466173
467075
  }
466174
467076
  },
466175
467077
  "title": "Record (detailed)"
@@ -466236,6 +467138,17 @@
466236
467138
  "path": "results.mp4",
466237
467139
  "engine": "ffmpeg"
466238
467140
  },
467141
+ {
467142
+ "path": "results.mp4",
467143
+ "checkpoints": true
467144
+ },
467145
+ {
467146
+ "path": "results.mp4",
467147
+ "checkpoints": {
467148
+ "maxVariation": 0.02,
467149
+ "directory": "baselines/results"
467150
+ }
467151
+ },
466239
467152
  {
466240
467153
  "path": "results.mp4",
466241
467154
  "engine": {
@@ -508354,9 +509267,10 @@
508354
509267
  "anyOf": [
508355
509268
  {
508356
509269
  "title": "Screenshot (simple)",
509270
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
508357
509271
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
508358
509272
  "type": "string",
508359
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509273
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
508360
509274
  "transform": [
508361
509275
  "trim"
508362
509276
  ]
@@ -508590,9 +509504,10 @@
508590
509504
  },
508591
509505
  "path": {
508592
509506
  "title": "Screenshot (simple)",
509507
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
508593
509508
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
508594
509509
  "type": "string",
508595
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509510
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
508596
509511
  "transform": [
508597
509512
  "trim"
508598
509513
  ]
@@ -508850,9 +509765,10 @@
508850
509765
  "schemas": {
508851
509766
  "path": {
508852
509767
  "title": "Screenshot (simple)",
509768
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
508853
509769
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
508854
509770
  "type": "string",
508855
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509771
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
508856
509772
  "transform": [
508857
509773
  "trim"
508858
509774
  ]
@@ -509086,9 +510002,10 @@
509086
510002
  },
509087
510003
  "path": {
509088
510004
  "title": "Screenshot (simple)",
510005
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
509089
510006
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
509090
510007
  "type": "string",
509091
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
510008
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509092
510009
  "transform": [
509093
510010
  "trim"
509094
510011
  ]
@@ -509562,9 +510479,10 @@
509562
510479
  },
509563
510480
  "path": {
509564
510481
  "title": "Screenshot (simple)",
510482
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
509565
510483
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
509566
510484
  "type": "string",
509567
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
510485
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509568
510486
  "transform": [
509569
510487
  "trim"
509570
510488
  ]
@@ -509946,6 +510864,7 @@
509946
510864
  "image.png",
509947
510865
  "static/images/image.png",
509948
510866
  "/User/manny/projects/doc-detective/static/images/image.png",
510867
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
509949
510868
  "https://example.com/static/images/image.png",
509950
510869
  {
509951
510870
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -512380,10 +513299,11 @@
512380
513299
  },
512381
513300
  "overwrite": {
512382
513301
  "type": "string",
512383
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
513302
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
512384
513303
  "enum": [
512385
513304
  "true",
512386
- "false"
513305
+ "false",
513306
+ "aboveVariation"
512387
513307
  ]
512388
513308
  },
512389
513309
  "name": {
@@ -512441,6 +513361,38 @@
512441
513361
  }
512442
513362
  }
512443
513363
  ]
513364
+ },
513365
+ "checkpoints": {
513366
+ "title": "Recording checkpoints",
513367
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
513368
+ "anyOf": [
513369
+ {
513370
+ "type": "boolean",
513371
+ "title": "Recording checkpoints (boolean)",
513372
+ "description": "If `true`, enables checkpoints with default settings."
513373
+ },
513374
+ {
513375
+ "type": "object",
513376
+ "title": "Recording checkpoints (detailed)",
513377
+ "additionalProperties": false,
513378
+ "properties": {
513379
+ "maxVariation": {
513380
+ "type": "number",
513381
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
513382
+ "default": 0.05,
513383
+ "minimum": 0,
513384
+ "maximum": 1
513385
+ },
513386
+ "directory": {
513387
+ "type": "string",
513388
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
513389
+ "transform": [
513390
+ "trim"
513391
+ ]
513392
+ }
513393
+ }
513394
+ }
513395
+ ]
512444
513396
  }
512445
513397
  },
512446
513398
  "title": "Record (detailed)"
@@ -512702,10 +513654,11 @@
512702
513654
  },
512703
513655
  "overwrite": {
512704
513656
  "type": "string",
512705
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
513657
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
512706
513658
  "enum": [
512707
513659
  "true",
512708
- "false"
513660
+ "false",
513661
+ "aboveVariation"
512709
513662
  ]
512710
513663
  },
512711
513664
  "name": {
@@ -512763,6 +513716,38 @@
512763
513716
  }
512764
513717
  }
512765
513718
  ]
513719
+ },
513720
+ "checkpoints": {
513721
+ "title": "Recording checkpoints",
513722
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
513723
+ "anyOf": [
513724
+ {
513725
+ "type": "boolean",
513726
+ "title": "Recording checkpoints (boolean)",
513727
+ "description": "If `true`, enables checkpoints with default settings."
513728
+ },
513729
+ {
513730
+ "type": "object",
513731
+ "title": "Recording checkpoints (detailed)",
513732
+ "additionalProperties": false,
513733
+ "properties": {
513734
+ "maxVariation": {
513735
+ "type": "number",
513736
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
513737
+ "default": 0.05,
513738
+ "minimum": 0,
513739
+ "maximum": 1
513740
+ },
513741
+ "directory": {
513742
+ "type": "string",
513743
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
513744
+ "transform": [
513745
+ "trim"
513746
+ ]
513747
+ }
513748
+ }
513749
+ }
513750
+ ]
512766
513751
  }
512767
513752
  },
512768
513753
  "title": "Record (detailed)"
@@ -512829,6 +513814,17 @@
512829
513814
  "path": "results.mp4",
512830
513815
  "engine": "ffmpeg"
512831
513816
  },
513817
+ {
513818
+ "path": "results.mp4",
513819
+ "checkpoints": true
513820
+ },
513821
+ {
513822
+ "path": "results.mp4",
513823
+ "checkpoints": {
513824
+ "maxVariation": 0.02,
513825
+ "directory": "baselines/results"
513826
+ }
513827
+ },
512832
513828
  {
512833
513829
  "path": "results.mp4",
512834
513830
  "engine": {
@@ -556600,9 +557596,10 @@
556600
557596
  "anyOf": [
556601
557597
  {
556602
557598
  "title": "Screenshot (simple)",
557599
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
556603
557600
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
556604
557601
  "type": "string",
556605
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557602
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
556606
557603
  "transform": [
556607
557604
  "trim"
556608
557605
  ]
@@ -556836,9 +557833,10 @@
556836
557833
  },
556837
557834
  "path": {
556838
557835
  "title": "Screenshot (simple)",
557836
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
556839
557837
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
556840
557838
  "type": "string",
556841
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557839
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
556842
557840
  "transform": [
556843
557841
  "trim"
556844
557842
  ]
@@ -557096,9 +558094,10 @@
557096
558094
  "schemas": {
557097
558095
  "path": {
557098
558096
  "title": "Screenshot (simple)",
558097
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
557099
558098
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
557100
558099
  "type": "string",
557101
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
558100
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557102
558101
  "transform": [
557103
558102
  "trim"
557104
558103
  ]
@@ -557332,9 +558331,10 @@
557332
558331
  },
557333
558332
  "path": {
557334
558333
  "title": "Screenshot (simple)",
558334
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
557335
558335
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
557336
558336
  "type": "string",
557337
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
558337
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557338
558338
  "transform": [
557339
558339
  "trim"
557340
558340
  ]
@@ -557808,9 +558808,10 @@
557808
558808
  },
557809
558809
  "path": {
557810
558810
  "title": "Screenshot (simple)",
558811
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
557811
558812
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
557812
558813
  "type": "string",
557813
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
558814
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557814
558815
  "transform": [
557815
558816
  "trim"
557816
558817
  ]
@@ -558192,6 +559193,7 @@
558192
559193
  "image.png",
558193
559194
  "static/images/image.png",
558194
559195
  "/User/manny/projects/doc-detective/static/images/image.png",
559196
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
558195
559197
  "https://example.com/static/images/image.png",
558196
559198
  {
558197
559199
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -560626,10 +561628,11 @@
560626
561628
  },
560627
561629
  "overwrite": {
560628
561630
  "type": "string",
560629
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
561631
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
560630
561632
  "enum": [
560631
561633
  "true",
560632
- "false"
561634
+ "false",
561635
+ "aboveVariation"
560633
561636
  ]
560634
561637
  },
560635
561638
  "name": {
@@ -560687,6 +561690,38 @@
560687
561690
  }
560688
561691
  }
560689
561692
  ]
561693
+ },
561694
+ "checkpoints": {
561695
+ "title": "Recording checkpoints",
561696
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
561697
+ "anyOf": [
561698
+ {
561699
+ "type": "boolean",
561700
+ "title": "Recording checkpoints (boolean)",
561701
+ "description": "If `true`, enables checkpoints with default settings."
561702
+ },
561703
+ {
561704
+ "type": "object",
561705
+ "title": "Recording checkpoints (detailed)",
561706
+ "additionalProperties": false,
561707
+ "properties": {
561708
+ "maxVariation": {
561709
+ "type": "number",
561710
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
561711
+ "default": 0.05,
561712
+ "minimum": 0,
561713
+ "maximum": 1
561714
+ },
561715
+ "directory": {
561716
+ "type": "string",
561717
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
561718
+ "transform": [
561719
+ "trim"
561720
+ ]
561721
+ }
561722
+ }
561723
+ }
561724
+ ]
560690
561725
  }
560691
561726
  },
560692
561727
  "title": "Record (detailed)"
@@ -560948,10 +561983,11 @@
560948
561983
  },
560949
561984
  "overwrite": {
560950
561985
  "type": "string",
560951
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
561986
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
560952
561987
  "enum": [
560953
561988
  "true",
560954
- "false"
561989
+ "false",
561990
+ "aboveVariation"
560955
561991
  ]
560956
561992
  },
560957
561993
  "name": {
@@ -561009,6 +562045,38 @@
561009
562045
  }
561010
562046
  }
561011
562047
  ]
562048
+ },
562049
+ "checkpoints": {
562050
+ "title": "Recording checkpoints",
562051
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
562052
+ "anyOf": [
562053
+ {
562054
+ "type": "boolean",
562055
+ "title": "Recording checkpoints (boolean)",
562056
+ "description": "If `true`, enables checkpoints with default settings."
562057
+ },
562058
+ {
562059
+ "type": "object",
562060
+ "title": "Recording checkpoints (detailed)",
562061
+ "additionalProperties": false,
562062
+ "properties": {
562063
+ "maxVariation": {
562064
+ "type": "number",
562065
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
562066
+ "default": 0.05,
562067
+ "minimum": 0,
562068
+ "maximum": 1
562069
+ },
562070
+ "directory": {
562071
+ "type": "string",
562072
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
562073
+ "transform": [
562074
+ "trim"
562075
+ ]
562076
+ }
562077
+ }
562078
+ }
562079
+ ]
561012
562080
  }
561013
562081
  },
561014
562082
  "title": "Record (detailed)"
@@ -561075,6 +562143,17 @@
561075
562143
  "path": "results.mp4",
561076
562144
  "engine": "ffmpeg"
561077
562145
  },
562146
+ {
562147
+ "path": "results.mp4",
562148
+ "checkpoints": true
562149
+ },
562150
+ {
562151
+ "path": "results.mp4",
562152
+ "checkpoints": {
562153
+ "maxVariation": 0.02,
562154
+ "directory": "baselines/results"
562155
+ }
562156
+ },
561078
562157
  {
561079
562158
  "path": "results.mp4",
561080
562159
  "engine": {
@@ -601501,9 +602580,10 @@
601501
602580
  "anyOf": [
601502
602581
  {
601503
602582
  "title": "Screenshot (simple)",
602583
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
601504
602584
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
601505
602585
  "type": "string",
601506
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602586
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
601507
602587
  "transform": [
601508
602588
  "trim"
601509
602589
  ]
@@ -601737,9 +602817,10 @@
601737
602817
  },
601738
602818
  "path": {
601739
602819
  "title": "Screenshot (simple)",
602820
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
601740
602821
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
601741
602822
  "type": "string",
601742
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602823
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
601743
602824
  "transform": [
601744
602825
  "trim"
601745
602826
  ]
@@ -601997,9 +603078,10 @@
601997
603078
  "schemas": {
601998
603079
  "path": {
601999
603080
  "title": "Screenshot (simple)",
603081
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
602000
603082
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
602001
603083
  "type": "string",
602002
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
603084
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602003
603085
  "transform": [
602004
603086
  "trim"
602005
603087
  ]
@@ -602233,9 +603315,10 @@
602233
603315
  },
602234
603316
  "path": {
602235
603317
  "title": "Screenshot (simple)",
603318
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
602236
603319
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
602237
603320
  "type": "string",
602238
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
603321
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602239
603322
  "transform": [
602240
603323
  "trim"
602241
603324
  ]
@@ -602709,9 +603792,10 @@
602709
603792
  },
602710
603793
  "path": {
602711
603794
  "title": "Screenshot (simple)",
603795
+ "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
602712
603796
  "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
602713
603797
  "type": "string",
602714
- "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
603798
+ "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602715
603799
  "transform": [
602716
603800
  "trim"
602717
603801
  ]
@@ -603093,6 +604177,7 @@
603093
604177
  "image.png",
603094
604178
  "static/images/image.png",
603095
604179
  "/User/manny/projects/doc-detective/static/images/image.png",
604180
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
603096
604181
  "https://example.com/static/images/image.png",
603097
604182
  {
603098
604183
  "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -605527,10 +606612,11 @@
605527
606612
  },
605528
606613
  "overwrite": {
605529
606614
  "type": "string",
605530
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
606615
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
605531
606616
  "enum": [
605532
606617
  "true",
605533
- "false"
606618
+ "false",
606619
+ "aboveVariation"
605534
606620
  ]
605535
606621
  },
605536
606622
  "name": {
@@ -605588,6 +606674,38 @@
605588
606674
  }
605589
606675
  }
605590
606676
  ]
606677
+ },
606678
+ "checkpoints": {
606679
+ "title": "Recording checkpoints",
606680
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
606681
+ "anyOf": [
606682
+ {
606683
+ "type": "boolean",
606684
+ "title": "Recording checkpoints (boolean)",
606685
+ "description": "If `true`, enables checkpoints with default settings."
606686
+ },
606687
+ {
606688
+ "type": "object",
606689
+ "title": "Recording checkpoints (detailed)",
606690
+ "additionalProperties": false,
606691
+ "properties": {
606692
+ "maxVariation": {
606693
+ "type": "number",
606694
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
606695
+ "default": 0.05,
606696
+ "minimum": 0,
606697
+ "maximum": 1
606698
+ },
606699
+ "directory": {
606700
+ "type": "string",
606701
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
606702
+ "transform": [
606703
+ "trim"
606704
+ ]
606705
+ }
606706
+ }
606707
+ }
606708
+ ]
605591
606709
  }
605592
606710
  },
605593
606711
  "title": "Record (detailed)"
@@ -605849,10 +606967,11 @@
605849
606967
  },
605850
606968
  "overwrite": {
605851
606969
  "type": "string",
605852
- "description": "If `true`, overwrites the existing recording at `path` if it exists.",
606970
+ "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
605853
606971
  "enum": [
605854
606972
  "true",
605855
- "false"
606973
+ "false",
606974
+ "aboveVariation"
605856
606975
  ]
605857
606976
  },
605858
606977
  "name": {
@@ -605910,6 +607029,38 @@
605910
607029
  }
605911
607030
  }
605912
607031
  ]
607032
+ },
607033
+ "checkpoints": {
607034
+ "title": "Recording checkpoints",
607035
+ "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
607036
+ "anyOf": [
607037
+ {
607038
+ "type": "boolean",
607039
+ "title": "Recording checkpoints (boolean)",
607040
+ "description": "If `true`, enables checkpoints with default settings."
607041
+ },
607042
+ {
607043
+ "type": "object",
607044
+ "title": "Recording checkpoints (detailed)",
607045
+ "additionalProperties": false,
607046
+ "properties": {
607047
+ "maxVariation": {
607048
+ "type": "number",
607049
+ "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
607050
+ "default": 0.05,
607051
+ "minimum": 0,
607052
+ "maximum": 1
607053
+ },
607054
+ "directory": {
607055
+ "type": "string",
607056
+ "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
607057
+ "transform": [
607058
+ "trim"
607059
+ ]
607060
+ }
607061
+ }
607062
+ }
607063
+ ]
605913
607064
  }
605914
607065
  },
605915
607066
  "title": "Record (detailed)"
@@ -605976,6 +607127,17 @@
605976
607127
  "path": "results.mp4",
605977
607128
  "engine": "ffmpeg"
605978
607129
  },
607130
+ {
607131
+ "path": "results.mp4",
607132
+ "checkpoints": true
607133
+ },
607134
+ {
607135
+ "path": "results.mp4",
607136
+ "checkpoints": {
607137
+ "maxVariation": 0.02,
607138
+ "directory": "baselines/results"
607139
+ }
607140
+ },
605979
607141
  {
605980
607142
  "path": "results.mp4",
605981
607143
  "engine": {