doc-detective-common 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 (9) hide show
  1. package/dist/index.cjs +1288 -126
  2. package/dist/schemas/schemas.json +1288 -126
  3. package/dist/types/generated/record_v3.d.ts +21 -2
  4. package/dist/types/generated/record_v3.d.ts.map +1 -1
  5. package/dist/types/generated/step_v3.d.ts +21 -2
  6. package/dist/types/generated/step_v3.d.ts.map +1 -1
  7. package/dist/types/generated/test_v3.d.ts +42 -4
  8. package/dist/types/generated/test_v3.d.ts.map +1 -1
  9. package/package.json +1 -1
package/dist/index.cjs CHANGED
@@ -30469,9 +30469,10 @@ var schemas_default = {
30469
30469
  anyOf: [
30470
30470
  {
30471
30471
  title: "Screenshot (simple)",
30472
+ $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 \u2014 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.",
30472
30473
  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.",
30473
30474
  type: "string",
30474
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30475
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30475
30476
  transform: [
30476
30477
  "trim"
30477
30478
  ]
@@ -30705,9 +30706,10 @@ var schemas_default = {
30705
30706
  },
30706
30707
  path: {
30707
30708
  title: "Screenshot (simple)",
30709
+ $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 \u2014 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.",
30708
30710
  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.",
30709
30711
  type: "string",
30710
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30712
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30711
30713
  transform: [
30712
30714
  "trim"
30713
30715
  ]
@@ -30965,9 +30967,10 @@ var schemas_default = {
30965
30967
  schemas: {
30966
30968
  path: {
30967
30969
  title: "Screenshot (simple)",
30970
+ $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 \u2014 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.",
30968
30971
  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.",
30969
30972
  type: "string",
30970
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30973
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
30971
30974
  transform: [
30972
30975
  "trim"
30973
30976
  ]
@@ -31201,9 +31204,10 @@ var schemas_default = {
31201
31204
  },
31202
31205
  path: {
31203
31206
  title: "Screenshot (simple)",
31207
+ $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 \u2014 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.",
31204
31208
  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.",
31205
31209
  type: "string",
31206
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31210
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31207
31211
  transform: [
31208
31212
  "trim"
31209
31213
  ]
@@ -31677,9 +31681,10 @@ var schemas_default = {
31677
31681
  },
31678
31682
  path: {
31679
31683
  title: "Screenshot (simple)",
31684
+ $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 \u2014 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.",
31680
31685
  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.",
31681
31686
  type: "string",
31682
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31687
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
31683
31688
  transform: [
31684
31689
  "trim"
31685
31690
  ]
@@ -32061,6 +32066,7 @@ var schemas_default = {
32061
32066
  "image.png",
32062
32067
  "static/images/image.png",
32063
32068
  "/User/manny/projects/doc-detective/static/images/image.png",
32069
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
32064
32070
  "https://example.com/static/images/image.png",
32065
32071
  {
32066
32072
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -34495,10 +34501,11 @@ var schemas_default = {
34495
34501
  },
34496
34502
  overwrite: {
34497
34503
  type: "string",
34498
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
34504
+ 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 \u2014 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`.",
34499
34505
  enum: [
34500
34506
  "true",
34501
- "false"
34507
+ "false",
34508
+ "aboveVariation"
34502
34509
  ]
34503
34510
  },
34504
34511
  name: {
@@ -34556,6 +34563,38 @@ var schemas_default = {
34556
34563
  }
34557
34564
  }
34558
34565
  ]
34566
+ },
34567
+ checkpoints: {
34568
+ title: "Recording checkpoints",
34569
+ 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.",
34570
+ anyOf: [
34571
+ {
34572
+ type: "boolean",
34573
+ title: "Recording checkpoints (boolean)",
34574
+ description: "If `true`, enables checkpoints with default settings."
34575
+ },
34576
+ {
34577
+ type: "object",
34578
+ title: "Recording checkpoints (detailed)",
34579
+ additionalProperties: false,
34580
+ properties: {
34581
+ maxVariation: {
34582
+ type: "number",
34583
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
34584
+ default: 0.05,
34585
+ minimum: 0,
34586
+ maximum: 1
34587
+ },
34588
+ directory: {
34589
+ type: "string",
34590
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
34591
+ transform: [
34592
+ "trim"
34593
+ ]
34594
+ }
34595
+ }
34596
+ }
34597
+ ]
34559
34598
  }
34560
34599
  },
34561
34600
  title: "Record (detailed)"
@@ -34817,10 +34856,11 @@ var schemas_default = {
34817
34856
  },
34818
34857
  overwrite: {
34819
34858
  type: "string",
34820
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
34859
+ 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 \u2014 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`.",
34821
34860
  enum: [
34822
34861
  "true",
34823
- "false"
34862
+ "false",
34863
+ "aboveVariation"
34824
34864
  ]
34825
34865
  },
34826
34866
  name: {
@@ -34878,6 +34918,38 @@ var schemas_default = {
34878
34918
  }
34879
34919
  }
34880
34920
  ]
34921
+ },
34922
+ checkpoints: {
34923
+ title: "Recording checkpoints",
34924
+ 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.",
34925
+ anyOf: [
34926
+ {
34927
+ type: "boolean",
34928
+ title: "Recording checkpoints (boolean)",
34929
+ description: "If `true`, enables checkpoints with default settings."
34930
+ },
34931
+ {
34932
+ type: "object",
34933
+ title: "Recording checkpoints (detailed)",
34934
+ additionalProperties: false,
34935
+ properties: {
34936
+ maxVariation: {
34937
+ type: "number",
34938
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
34939
+ default: 0.05,
34940
+ minimum: 0,
34941
+ maximum: 1
34942
+ },
34943
+ directory: {
34944
+ type: "string",
34945
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
34946
+ transform: [
34947
+ "trim"
34948
+ ]
34949
+ }
34950
+ }
34951
+ }
34952
+ ]
34881
34953
  }
34882
34954
  },
34883
34955
  title: "Record (detailed)"
@@ -34944,6 +35016,17 @@ var schemas_default = {
34944
35016
  path: "results.mp4",
34945
35017
  engine: "ffmpeg"
34946
35018
  },
35019
+ {
35020
+ path: "results.mp4",
35021
+ checkpoints: true
35022
+ },
35023
+ {
35024
+ path: "results.mp4",
35025
+ checkpoints: {
35026
+ maxVariation: 0.02,
35027
+ directory: "baselines/results"
35028
+ }
35029
+ },
34947
35030
  {
34948
35031
  path: "results.mp4",
34949
35032
  engine: {
@@ -76108,9 +76191,10 @@ var schemas_default = {
76108
76191
  anyOf: [
76109
76192
  {
76110
76193
  title: "Screenshot (simple)",
76194
+ $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 \u2014 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.",
76111
76195
  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.",
76112
76196
  type: "string",
76113
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76197
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76114
76198
  transform: [
76115
76199
  "trim"
76116
76200
  ]
@@ -76344,9 +76428,10 @@ var schemas_default = {
76344
76428
  },
76345
76429
  path: {
76346
76430
  title: "Screenshot (simple)",
76431
+ $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 \u2014 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.",
76347
76432
  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.",
76348
76433
  type: "string",
76349
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76434
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76350
76435
  transform: [
76351
76436
  "trim"
76352
76437
  ]
@@ -76604,9 +76689,10 @@ var schemas_default = {
76604
76689
  schemas: {
76605
76690
  path: {
76606
76691
  title: "Screenshot (simple)",
76692
+ $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 \u2014 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.",
76607
76693
  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.",
76608
76694
  type: "string",
76609
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76695
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76610
76696
  transform: [
76611
76697
  "trim"
76612
76698
  ]
@@ -76840,9 +76926,10 @@ var schemas_default = {
76840
76926
  },
76841
76927
  path: {
76842
76928
  title: "Screenshot (simple)",
76929
+ $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 \u2014 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.",
76843
76930
  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.",
76844
76931
  type: "string",
76845
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76932
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
76846
76933
  transform: [
76847
76934
  "trim"
76848
76935
  ]
@@ -77316,9 +77403,10 @@ var schemas_default = {
77316
77403
  },
77317
77404
  path: {
77318
77405
  title: "Screenshot (simple)",
77406
+ $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 \u2014 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.",
77319
77407
  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.",
77320
77408
  type: "string",
77321
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
77409
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
77322
77410
  transform: [
77323
77411
  "trim"
77324
77412
  ]
@@ -77700,6 +77788,7 @@ var schemas_default = {
77700
77788
  "image.png",
77701
77789
  "static/images/image.png",
77702
77790
  "/User/manny/projects/doc-detective/static/images/image.png",
77791
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
77703
77792
  "https://example.com/static/images/image.png",
77704
77793
  {
77705
77794
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -80134,10 +80223,11 @@ var schemas_default = {
80134
80223
  },
80135
80224
  overwrite: {
80136
80225
  type: "string",
80137
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
80226
+ 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 \u2014 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`.",
80138
80227
  enum: [
80139
80228
  "true",
80140
- "false"
80229
+ "false",
80230
+ "aboveVariation"
80141
80231
  ]
80142
80232
  },
80143
80233
  name: {
@@ -80195,6 +80285,38 @@ var schemas_default = {
80195
80285
  }
80196
80286
  }
80197
80287
  ]
80288
+ },
80289
+ checkpoints: {
80290
+ title: "Recording checkpoints",
80291
+ 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.",
80292
+ anyOf: [
80293
+ {
80294
+ type: "boolean",
80295
+ title: "Recording checkpoints (boolean)",
80296
+ description: "If `true`, enables checkpoints with default settings."
80297
+ },
80298
+ {
80299
+ type: "object",
80300
+ title: "Recording checkpoints (detailed)",
80301
+ additionalProperties: false,
80302
+ properties: {
80303
+ maxVariation: {
80304
+ type: "number",
80305
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
80306
+ default: 0.05,
80307
+ minimum: 0,
80308
+ maximum: 1
80309
+ },
80310
+ directory: {
80311
+ type: "string",
80312
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
80313
+ transform: [
80314
+ "trim"
80315
+ ]
80316
+ }
80317
+ }
80318
+ }
80319
+ ]
80198
80320
  }
80199
80321
  },
80200
80322
  title: "Record (detailed)"
@@ -80456,10 +80578,11 @@ var schemas_default = {
80456
80578
  },
80457
80579
  overwrite: {
80458
80580
  type: "string",
80459
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
80581
+ 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 \u2014 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`.",
80460
80582
  enum: [
80461
80583
  "true",
80462
- "false"
80584
+ "false",
80585
+ "aboveVariation"
80463
80586
  ]
80464
80587
  },
80465
80588
  name: {
@@ -80517,6 +80640,38 @@ var schemas_default = {
80517
80640
  }
80518
80641
  }
80519
80642
  ]
80643
+ },
80644
+ checkpoints: {
80645
+ title: "Recording checkpoints",
80646
+ 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.",
80647
+ anyOf: [
80648
+ {
80649
+ type: "boolean",
80650
+ title: "Recording checkpoints (boolean)",
80651
+ description: "If `true`, enables checkpoints with default settings."
80652
+ },
80653
+ {
80654
+ type: "object",
80655
+ title: "Recording checkpoints (detailed)",
80656
+ additionalProperties: false,
80657
+ properties: {
80658
+ maxVariation: {
80659
+ type: "number",
80660
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
80661
+ default: 0.05,
80662
+ minimum: 0,
80663
+ maximum: 1
80664
+ },
80665
+ directory: {
80666
+ type: "string",
80667
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
80668
+ transform: [
80669
+ "trim"
80670
+ ]
80671
+ }
80672
+ }
80673
+ }
80674
+ ]
80520
80675
  }
80521
80676
  },
80522
80677
  title: "Record (detailed)"
@@ -80583,6 +80738,17 @@ var schemas_default = {
80583
80738
  path: "results.mp4",
80584
80739
  engine: "ffmpeg"
80585
80740
  },
80741
+ {
80742
+ path: "results.mp4",
80743
+ checkpoints: true
80744
+ },
80745
+ {
80746
+ path: "results.mp4",
80747
+ checkpoints: {
80748
+ maxVariation: 0.02,
80749
+ directory: "baselines/results"
80750
+ }
80751
+ },
80586
80752
  {
80587
80753
  path: "results.mp4",
80588
80754
  engine: {
@@ -106419,10 +106585,11 @@ var schemas_default = {
106419
106585
  },
106420
106586
  overwrite: {
106421
106587
  type: "string",
106422
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
106588
+ 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 \u2014 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`.",
106423
106589
  enum: [
106424
106590
  "true",
106425
- "false"
106591
+ "false",
106592
+ "aboveVariation"
106426
106593
  ]
106427
106594
  },
106428
106595
  name: {
@@ -106480,6 +106647,38 @@ var schemas_default = {
106480
106647
  }
106481
106648
  }
106482
106649
  ]
106650
+ },
106651
+ checkpoints: {
106652
+ title: "Recording checkpoints",
106653
+ 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.",
106654
+ anyOf: [
106655
+ {
106656
+ type: "boolean",
106657
+ title: "Recording checkpoints (boolean)",
106658
+ description: "If `true`, enables checkpoints with default settings."
106659
+ },
106660
+ {
106661
+ type: "object",
106662
+ title: "Recording checkpoints (detailed)",
106663
+ additionalProperties: false,
106664
+ properties: {
106665
+ maxVariation: {
106666
+ type: "number",
106667
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
106668
+ default: 0.05,
106669
+ minimum: 0,
106670
+ maximum: 1
106671
+ },
106672
+ directory: {
106673
+ type: "string",
106674
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
106675
+ transform: [
106676
+ "trim"
106677
+ ]
106678
+ }
106679
+ }
106680
+ }
106681
+ ]
106483
106682
  }
106484
106683
  },
106485
106684
  title: "Record (detailed)"
@@ -106741,10 +106940,11 @@ var schemas_default = {
106741
106940
  },
106742
106941
  overwrite: {
106743
106942
  type: "string",
106744
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
106943
+ 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 \u2014 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`.",
106745
106944
  enum: [
106746
106945
  "true",
106747
- "false"
106946
+ "false",
106947
+ "aboveVariation"
106748
106948
  ]
106749
106949
  },
106750
106950
  name: {
@@ -106802,6 +107002,38 @@ var schemas_default = {
106802
107002
  }
106803
107003
  }
106804
107004
  ]
107005
+ },
107006
+ checkpoints: {
107007
+ title: "Recording checkpoints",
107008
+ 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.",
107009
+ anyOf: [
107010
+ {
107011
+ type: "boolean",
107012
+ title: "Recording checkpoints (boolean)",
107013
+ description: "If `true`, enables checkpoints with default settings."
107014
+ },
107015
+ {
107016
+ type: "object",
107017
+ title: "Recording checkpoints (detailed)",
107018
+ additionalProperties: false,
107019
+ properties: {
107020
+ maxVariation: {
107021
+ type: "number",
107022
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
107023
+ default: 0.05,
107024
+ minimum: 0,
107025
+ maximum: 1
107026
+ },
107027
+ directory: {
107028
+ type: "string",
107029
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
107030
+ transform: [
107031
+ "trim"
107032
+ ]
107033
+ }
107034
+ }
107035
+ }
107036
+ ]
106805
107037
  }
106806
107038
  },
106807
107039
  title: "Record (detailed)"
@@ -106868,6 +107100,17 @@ var schemas_default = {
106868
107100
  path: "results.mp4",
106869
107101
  engine: "ffmpeg"
106870
107102
  },
107103
+ {
107104
+ path: "results.mp4",
107105
+ checkpoints: true
107106
+ },
107107
+ {
107108
+ path: "results.mp4",
107109
+ checkpoints: {
107110
+ maxVariation: 0.02,
107111
+ directory: "baselines/results"
107112
+ }
107113
+ },
106871
107114
  {
106872
107115
  path: "results.mp4",
106873
107116
  engine: {
@@ -135034,9 +135277,10 @@ var schemas_default = {
135034
135277
  anyOf: [
135035
135278
  {
135036
135279
  title: "Screenshot (simple)",
135280
+ $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 \u2014 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.",
135037
135281
  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.",
135038
135282
  type: "string",
135039
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135283
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135040
135284
  transform: [
135041
135285
  "trim"
135042
135286
  ]
@@ -135270,9 +135514,10 @@ var schemas_default = {
135270
135514
  },
135271
135515
  path: {
135272
135516
  title: "Screenshot (simple)",
135517
+ $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 \u2014 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.",
135273
135518
  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.",
135274
135519
  type: "string",
135275
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135520
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135276
135521
  transform: [
135277
135522
  "trim"
135278
135523
  ]
@@ -135530,9 +135775,10 @@ var schemas_default = {
135530
135775
  schemas: {
135531
135776
  path: {
135532
135777
  title: "Screenshot (simple)",
135778
+ $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 \u2014 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.",
135533
135779
  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.",
135534
135780
  type: "string",
135535
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135781
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135536
135782
  transform: [
135537
135783
  "trim"
135538
135784
  ]
@@ -135766,9 +136012,10 @@ var schemas_default = {
135766
136012
  },
135767
136013
  path: {
135768
136014
  title: "Screenshot (simple)",
136015
+ $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 \u2014 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.",
135769
136016
  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.",
135770
136017
  type: "string",
135771
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
136018
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
135772
136019
  transform: [
135773
136020
  "trim"
135774
136021
  ]
@@ -136242,9 +136489,10 @@ var schemas_default = {
136242
136489
  },
136243
136490
  path: {
136244
136491
  title: "Screenshot (simple)",
136492
+ $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 \u2014 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.",
136245
136493
  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.",
136246
136494
  type: "string",
136247
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
136495
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
136248
136496
  transform: [
136249
136497
  "trim"
136250
136498
  ]
@@ -136626,6 +136874,7 @@ var schemas_default = {
136626
136874
  "image.png",
136627
136875
  "static/images/image.png",
136628
136876
  "/User/manny/projects/doc-detective/static/images/image.png",
136877
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
136629
136878
  "https://example.com/static/images/image.png",
136630
136879
  {
136631
136880
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -139060,10 +139309,11 @@ var schemas_default = {
139060
139309
  },
139061
139310
  overwrite: {
139062
139311
  type: "string",
139063
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
139312
+ 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 \u2014 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`.",
139064
139313
  enum: [
139065
139314
  "true",
139066
- "false"
139315
+ "false",
139316
+ "aboveVariation"
139067
139317
  ]
139068
139318
  },
139069
139319
  name: {
@@ -139121,6 +139371,38 @@ var schemas_default = {
139121
139371
  }
139122
139372
  }
139123
139373
  ]
139374
+ },
139375
+ checkpoints: {
139376
+ title: "Recording checkpoints",
139377
+ 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.",
139378
+ anyOf: [
139379
+ {
139380
+ type: "boolean",
139381
+ title: "Recording checkpoints (boolean)",
139382
+ description: "If `true`, enables checkpoints with default settings."
139383
+ },
139384
+ {
139385
+ type: "object",
139386
+ title: "Recording checkpoints (detailed)",
139387
+ additionalProperties: false,
139388
+ properties: {
139389
+ maxVariation: {
139390
+ type: "number",
139391
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
139392
+ default: 0.05,
139393
+ minimum: 0,
139394
+ maximum: 1
139395
+ },
139396
+ directory: {
139397
+ type: "string",
139398
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
139399
+ transform: [
139400
+ "trim"
139401
+ ]
139402
+ }
139403
+ }
139404
+ }
139405
+ ]
139124
139406
  }
139125
139407
  },
139126
139408
  title: "Record (detailed)"
@@ -139382,10 +139664,11 @@ var schemas_default = {
139382
139664
  },
139383
139665
  overwrite: {
139384
139666
  type: "string",
139385
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
139667
+ 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 \u2014 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`.",
139386
139668
  enum: [
139387
139669
  "true",
139388
- "false"
139670
+ "false",
139671
+ "aboveVariation"
139389
139672
  ]
139390
139673
  },
139391
139674
  name: {
@@ -139443,6 +139726,38 @@ var schemas_default = {
139443
139726
  }
139444
139727
  }
139445
139728
  ]
139729
+ },
139730
+ checkpoints: {
139731
+ title: "Recording checkpoints",
139732
+ 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.",
139733
+ anyOf: [
139734
+ {
139735
+ type: "boolean",
139736
+ title: "Recording checkpoints (boolean)",
139737
+ description: "If `true`, enables checkpoints with default settings."
139738
+ },
139739
+ {
139740
+ type: "object",
139741
+ title: "Recording checkpoints (detailed)",
139742
+ additionalProperties: false,
139743
+ properties: {
139744
+ maxVariation: {
139745
+ type: "number",
139746
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
139747
+ default: 0.05,
139748
+ minimum: 0,
139749
+ maximum: 1
139750
+ },
139751
+ directory: {
139752
+ type: "string",
139753
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
139754
+ transform: [
139755
+ "trim"
139756
+ ]
139757
+ }
139758
+ }
139759
+ }
139760
+ ]
139446
139761
  }
139447
139762
  },
139448
139763
  title: "Record (detailed)"
@@ -139509,6 +139824,17 @@ var schemas_default = {
139509
139824
  path: "results.mp4",
139510
139825
  engine: "ffmpeg"
139511
139826
  },
139827
+ {
139828
+ path: "results.mp4",
139829
+ checkpoints: true
139830
+ },
139831
+ {
139832
+ path: "results.mp4",
139833
+ checkpoints: {
139834
+ maxVariation: 0.02,
139835
+ directory: "baselines/results"
139836
+ }
139837
+ },
139512
139838
  {
139513
139839
  path: "results.mp4",
139514
139840
  engine: {
@@ -180673,9 +180999,10 @@ var schemas_default = {
180673
180999
  anyOf: [
180674
181000
  {
180675
181001
  title: "Screenshot (simple)",
181002
+ $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 \u2014 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.",
180676
181003
  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.",
180677
181004
  type: "string",
180678
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181005
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
180679
181006
  transform: [
180680
181007
  "trim"
180681
181008
  ]
@@ -180909,9 +181236,10 @@ var schemas_default = {
180909
181236
  },
180910
181237
  path: {
180911
181238
  title: "Screenshot (simple)",
181239
+ $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 \u2014 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.",
180912
181240
  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.",
180913
181241
  type: "string",
180914
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181242
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
180915
181243
  transform: [
180916
181244
  "trim"
180917
181245
  ]
@@ -181169,9 +181497,10 @@ var schemas_default = {
181169
181497
  schemas: {
181170
181498
  path: {
181171
181499
  title: "Screenshot (simple)",
181500
+ $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 \u2014 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.",
181172
181501
  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.",
181173
181502
  type: "string",
181174
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181503
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181175
181504
  transform: [
181176
181505
  "trim"
181177
181506
  ]
@@ -181405,9 +181734,10 @@ var schemas_default = {
181405
181734
  },
181406
181735
  path: {
181407
181736
  title: "Screenshot (simple)",
181737
+ $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 \u2014 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.",
181408
181738
  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.",
181409
181739
  type: "string",
181410
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181740
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181411
181741
  transform: [
181412
181742
  "trim"
181413
181743
  ]
@@ -181881,9 +182211,10 @@ var schemas_default = {
181881
182211
  },
181882
182212
  path: {
181883
182213
  title: "Screenshot (simple)",
182214
+ $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 \u2014 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.",
181884
182215
  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.",
181885
182216
  type: "string",
181886
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
182217
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
181887
182218
  transform: [
181888
182219
  "trim"
181889
182220
  ]
@@ -182265,6 +182596,7 @@ var schemas_default = {
182265
182596
  "image.png",
182266
182597
  "static/images/image.png",
182267
182598
  "/User/manny/projects/doc-detective/static/images/image.png",
182599
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
182268
182600
  "https://example.com/static/images/image.png",
182269
182601
  {
182270
182602
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -184699,10 +185031,11 @@ var schemas_default = {
184699
185031
  },
184700
185032
  overwrite: {
184701
185033
  type: "string",
184702
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
185034
+ 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 \u2014 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`.",
184703
185035
  enum: [
184704
185036
  "true",
184705
- "false"
185037
+ "false",
185038
+ "aboveVariation"
184706
185039
  ]
184707
185040
  },
184708
185041
  name: {
@@ -184760,6 +185093,38 @@ var schemas_default = {
184760
185093
  }
184761
185094
  }
184762
185095
  ]
185096
+ },
185097
+ checkpoints: {
185098
+ title: "Recording checkpoints",
185099
+ 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.",
185100
+ anyOf: [
185101
+ {
185102
+ type: "boolean",
185103
+ title: "Recording checkpoints (boolean)",
185104
+ description: "If `true`, enables checkpoints with default settings."
185105
+ },
185106
+ {
185107
+ type: "object",
185108
+ title: "Recording checkpoints (detailed)",
185109
+ additionalProperties: false,
185110
+ properties: {
185111
+ maxVariation: {
185112
+ type: "number",
185113
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
185114
+ default: 0.05,
185115
+ minimum: 0,
185116
+ maximum: 1
185117
+ },
185118
+ directory: {
185119
+ type: "string",
185120
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
185121
+ transform: [
185122
+ "trim"
185123
+ ]
185124
+ }
185125
+ }
185126
+ }
185127
+ ]
184763
185128
  }
184764
185129
  },
184765
185130
  title: "Record (detailed)"
@@ -185021,10 +185386,11 @@ var schemas_default = {
185021
185386
  },
185022
185387
  overwrite: {
185023
185388
  type: "string",
185024
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
185389
+ 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 \u2014 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`.",
185025
185390
  enum: [
185026
185391
  "true",
185027
- "false"
185392
+ "false",
185393
+ "aboveVariation"
185028
185394
  ]
185029
185395
  },
185030
185396
  name: {
@@ -185082,6 +185448,38 @@ var schemas_default = {
185082
185448
  }
185083
185449
  }
185084
185450
  ]
185451
+ },
185452
+ checkpoints: {
185453
+ title: "Recording checkpoints",
185454
+ 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.",
185455
+ anyOf: [
185456
+ {
185457
+ type: "boolean",
185458
+ title: "Recording checkpoints (boolean)",
185459
+ description: "If `true`, enables checkpoints with default settings."
185460
+ },
185461
+ {
185462
+ type: "object",
185463
+ title: "Recording checkpoints (detailed)",
185464
+ additionalProperties: false,
185465
+ properties: {
185466
+ maxVariation: {
185467
+ type: "number",
185468
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
185469
+ default: 0.05,
185470
+ minimum: 0,
185471
+ maximum: 1
185472
+ },
185473
+ directory: {
185474
+ type: "string",
185475
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
185476
+ transform: [
185477
+ "trim"
185478
+ ]
185479
+ }
185480
+ }
185481
+ }
185482
+ ]
185085
185483
  }
185086
185484
  },
185087
185485
  title: "Record (detailed)"
@@ -185148,6 +185546,17 @@ var schemas_default = {
185148
185546
  path: "results.mp4",
185149
185547
  engine: "ffmpeg"
185150
185548
  },
185549
+ {
185550
+ path: "results.mp4",
185551
+ checkpoints: true
185552
+ },
185553
+ {
185554
+ path: "results.mp4",
185555
+ checkpoints: {
185556
+ maxVariation: 0.02,
185557
+ directory: "baselines/results"
185558
+ }
185559
+ },
185151
185560
  {
185152
185561
  path: "results.mp4",
185153
185562
  engine: {
@@ -228051,9 +228460,10 @@ var schemas_default = {
228051
228460
  anyOf: [
228052
228461
  {
228053
228462
  title: "Screenshot (simple)",
228463
+ $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 \u2014 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.",
228054
228464
  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.",
228055
228465
  type: "string",
228056
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228466
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228057
228467
  transform: [
228058
228468
  "trim"
228059
228469
  ]
@@ -228287,9 +228697,10 @@ var schemas_default = {
228287
228697
  },
228288
228698
  path: {
228289
228699
  title: "Screenshot (simple)",
228700
+ $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 \u2014 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.",
228290
228701
  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.",
228291
228702
  type: "string",
228292
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228703
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228293
228704
  transform: [
228294
228705
  "trim"
228295
228706
  ]
@@ -228547,9 +228958,10 @@ var schemas_default = {
228547
228958
  schemas: {
228548
228959
  path: {
228549
228960
  title: "Screenshot (simple)",
228961
+ $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 \u2014 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.",
228550
228962
  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.",
228551
228963
  type: "string",
228552
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228964
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228553
228965
  transform: [
228554
228966
  "trim"
228555
228967
  ]
@@ -228783,9 +229195,10 @@ var schemas_default = {
228783
229195
  },
228784
229196
  path: {
228785
229197
  title: "Screenshot (simple)",
229198
+ $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 \u2014 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.",
228786
229199
  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.",
228787
229200
  type: "string",
228788
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
229201
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
228789
229202
  transform: [
228790
229203
  "trim"
228791
229204
  ]
@@ -229259,9 +229672,10 @@ var schemas_default = {
229259
229672
  },
229260
229673
  path: {
229261
229674
  title: "Screenshot (simple)",
229675
+ $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 \u2014 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.",
229262
229676
  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.",
229263
229677
  type: "string",
229264
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
229678
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
229265
229679
  transform: [
229266
229680
  "trim"
229267
229681
  ]
@@ -229643,6 +230057,7 @@ var schemas_default = {
229643
230057
  "image.png",
229644
230058
  "static/images/image.png",
229645
230059
  "/User/manny/projects/doc-detective/static/images/image.png",
230060
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
229646
230061
  "https://example.com/static/images/image.png",
229647
230062
  {
229648
230063
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -232077,10 +232492,11 @@ var schemas_default = {
232077
232492
  },
232078
232493
  overwrite: {
232079
232494
  type: "string",
232080
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
232495
+ 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 \u2014 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`.",
232081
232496
  enum: [
232082
232497
  "true",
232083
- "false"
232498
+ "false",
232499
+ "aboveVariation"
232084
232500
  ]
232085
232501
  },
232086
232502
  name: {
@@ -232138,6 +232554,38 @@ var schemas_default = {
232138
232554
  }
232139
232555
  }
232140
232556
  ]
232557
+ },
232558
+ checkpoints: {
232559
+ title: "Recording checkpoints",
232560
+ 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.",
232561
+ anyOf: [
232562
+ {
232563
+ type: "boolean",
232564
+ title: "Recording checkpoints (boolean)",
232565
+ description: "If `true`, enables checkpoints with default settings."
232566
+ },
232567
+ {
232568
+ type: "object",
232569
+ title: "Recording checkpoints (detailed)",
232570
+ additionalProperties: false,
232571
+ properties: {
232572
+ maxVariation: {
232573
+ type: "number",
232574
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
232575
+ default: 0.05,
232576
+ minimum: 0,
232577
+ maximum: 1
232578
+ },
232579
+ directory: {
232580
+ type: "string",
232581
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
232582
+ transform: [
232583
+ "trim"
232584
+ ]
232585
+ }
232586
+ }
232587
+ }
232588
+ ]
232141
232589
  }
232142
232590
  },
232143
232591
  title: "Record (detailed)"
@@ -232399,10 +232847,11 @@ var schemas_default = {
232399
232847
  },
232400
232848
  overwrite: {
232401
232849
  type: "string",
232402
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
232850
+ 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 \u2014 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`.",
232403
232851
  enum: [
232404
232852
  "true",
232405
- "false"
232853
+ "false",
232854
+ "aboveVariation"
232406
232855
  ]
232407
232856
  },
232408
232857
  name: {
@@ -232460,6 +232909,38 @@ var schemas_default = {
232460
232909
  }
232461
232910
  }
232462
232911
  ]
232912
+ },
232913
+ checkpoints: {
232914
+ title: "Recording checkpoints",
232915
+ 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.",
232916
+ anyOf: [
232917
+ {
232918
+ type: "boolean",
232919
+ title: "Recording checkpoints (boolean)",
232920
+ description: "If `true`, enables checkpoints with default settings."
232921
+ },
232922
+ {
232923
+ type: "object",
232924
+ title: "Recording checkpoints (detailed)",
232925
+ additionalProperties: false,
232926
+ properties: {
232927
+ maxVariation: {
232928
+ type: "number",
232929
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
232930
+ default: 0.05,
232931
+ minimum: 0,
232932
+ maximum: 1
232933
+ },
232934
+ directory: {
232935
+ type: "string",
232936
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
232937
+ transform: [
232938
+ "trim"
232939
+ ]
232940
+ }
232941
+ }
232942
+ }
232943
+ ]
232463
232944
  }
232464
232945
  },
232465
232946
  title: "Record (detailed)"
@@ -232526,6 +233007,17 @@ var schemas_default = {
232526
233007
  path: "results.mp4",
232527
233008
  engine: "ffmpeg"
232528
233009
  },
233010
+ {
233011
+ path: "results.mp4",
233012
+ checkpoints: true
233013
+ },
233014
+ {
233015
+ path: "results.mp4",
233016
+ checkpoints: {
233017
+ maxVariation: 0.02,
233018
+ directory: "baselines/results"
233019
+ }
233020
+ },
232529
233021
  {
232530
233022
  path: "results.mp4",
232531
233023
  engine: {
@@ -272952,9 +273444,10 @@ var schemas_default = {
272952
273444
  anyOf: [
272953
273445
  {
272954
273446
  title: "Screenshot (simple)",
273447
+ $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 \u2014 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.",
272955
273448
  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.",
272956
273449
  type: "string",
272957
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273450
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
272958
273451
  transform: [
272959
273452
  "trim"
272960
273453
  ]
@@ -273188,9 +273681,10 @@ var schemas_default = {
273188
273681
  },
273189
273682
  path: {
273190
273683
  title: "Screenshot (simple)",
273684
+ $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 \u2014 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.",
273191
273685
  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.",
273192
273686
  type: "string",
273193
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273687
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273194
273688
  transform: [
273195
273689
  "trim"
273196
273690
  ]
@@ -273448,9 +273942,10 @@ var schemas_default = {
273448
273942
  schemas: {
273449
273943
  path: {
273450
273944
  title: "Screenshot (simple)",
273945
+ $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 \u2014 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.",
273451
273946
  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.",
273452
273947
  type: "string",
273453
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273948
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273454
273949
  transform: [
273455
273950
  "trim"
273456
273951
  ]
@@ -273684,9 +274179,10 @@ var schemas_default = {
273684
274179
  },
273685
274180
  path: {
273686
274181
  title: "Screenshot (simple)",
274182
+ $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 \u2014 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.",
273687
274183
  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.",
273688
274184
  type: "string",
273689
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
274185
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
273690
274186
  transform: [
273691
274187
  "trim"
273692
274188
  ]
@@ -274160,9 +274656,10 @@ var schemas_default = {
274160
274656
  },
274161
274657
  path: {
274162
274658
  title: "Screenshot (simple)",
274659
+ $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 \u2014 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.",
274163
274660
  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.",
274164
274661
  type: "string",
274165
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
274662
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
274166
274663
  transform: [
274167
274664
  "trim"
274168
274665
  ]
@@ -274544,6 +275041,7 @@ var schemas_default = {
274544
275041
  "image.png",
274545
275042
  "static/images/image.png",
274546
275043
  "/User/manny/projects/doc-detective/static/images/image.png",
275044
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
274547
275045
  "https://example.com/static/images/image.png",
274548
275046
  {
274549
275047
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -276978,10 +277476,11 @@ var schemas_default = {
276978
277476
  },
276979
277477
  overwrite: {
276980
277478
  type: "string",
276981
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
277479
+ 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 \u2014 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`.",
276982
277480
  enum: [
276983
277481
  "true",
276984
- "false"
277482
+ "false",
277483
+ "aboveVariation"
276985
277484
  ]
276986
277485
  },
276987
277486
  name: {
@@ -277039,6 +277538,38 @@ var schemas_default = {
277039
277538
  }
277040
277539
  }
277041
277540
  ]
277541
+ },
277542
+ checkpoints: {
277543
+ title: "Recording checkpoints",
277544
+ 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.",
277545
+ anyOf: [
277546
+ {
277547
+ type: "boolean",
277548
+ title: "Recording checkpoints (boolean)",
277549
+ description: "If `true`, enables checkpoints with default settings."
277550
+ },
277551
+ {
277552
+ type: "object",
277553
+ title: "Recording checkpoints (detailed)",
277554
+ additionalProperties: false,
277555
+ properties: {
277556
+ maxVariation: {
277557
+ type: "number",
277558
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
277559
+ default: 0.05,
277560
+ minimum: 0,
277561
+ maximum: 1
277562
+ },
277563
+ directory: {
277564
+ type: "string",
277565
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
277566
+ transform: [
277567
+ "trim"
277568
+ ]
277569
+ }
277570
+ }
277571
+ }
277572
+ ]
277042
277573
  }
277043
277574
  },
277044
277575
  title: "Record (detailed)"
@@ -277300,10 +277831,11 @@ var schemas_default = {
277300
277831
  },
277301
277832
  overwrite: {
277302
277833
  type: "string",
277303
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
277834
+ 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 \u2014 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`.",
277304
277835
  enum: [
277305
277836
  "true",
277306
- "false"
277837
+ "false",
277838
+ "aboveVariation"
277307
277839
  ]
277308
277840
  },
277309
277841
  name: {
@@ -277361,6 +277893,38 @@ var schemas_default = {
277361
277893
  }
277362
277894
  }
277363
277895
  ]
277896
+ },
277897
+ checkpoints: {
277898
+ title: "Recording checkpoints",
277899
+ 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.",
277900
+ anyOf: [
277901
+ {
277902
+ type: "boolean",
277903
+ title: "Recording checkpoints (boolean)",
277904
+ description: "If `true`, enables checkpoints with default settings."
277905
+ },
277906
+ {
277907
+ type: "object",
277908
+ title: "Recording checkpoints (detailed)",
277909
+ additionalProperties: false,
277910
+ properties: {
277911
+ maxVariation: {
277912
+ type: "number",
277913
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
277914
+ default: 0.05,
277915
+ minimum: 0,
277916
+ maximum: 1
277917
+ },
277918
+ directory: {
277919
+ type: "string",
277920
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
277921
+ transform: [
277922
+ "trim"
277923
+ ]
277924
+ }
277925
+ }
277926
+ }
277927
+ ]
277364
277928
  }
277365
277929
  },
277366
277930
  title: "Record (detailed)"
@@ -277427,6 +277991,17 @@ var schemas_default = {
277427
277991
  path: "results.mp4",
277428
277992
  engine: "ffmpeg"
277429
277993
  },
277994
+ {
277995
+ path: "results.mp4",
277996
+ checkpoints: true
277997
+ },
277998
+ {
277999
+ path: "results.mp4",
278000
+ checkpoints: {
278001
+ maxVariation: 0.02,
278002
+ directory: "baselines/results"
278003
+ }
278004
+ },
277430
278005
  {
277431
278006
  path: "results.mp4",
277432
278007
  engine: {
@@ -320814,9 +321389,10 @@ var schemas_default = {
320814
321389
  anyOf: [
320815
321390
  {
320816
321391
  title: "Screenshot (simple)",
321392
+ $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 \u2014 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.",
320817
321393
  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.",
320818
321394
  type: "string",
320819
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321395
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
320820
321396
  transform: [
320821
321397
  "trim"
320822
321398
  ]
@@ -321050,9 +321626,10 @@ var schemas_default = {
321050
321626
  },
321051
321627
  path: {
321052
321628
  title: "Screenshot (simple)",
321629
+ $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 \u2014 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.",
321053
321630
  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.",
321054
321631
  type: "string",
321055
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321632
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321056
321633
  transform: [
321057
321634
  "trim"
321058
321635
  ]
@@ -321310,9 +321887,10 @@ var schemas_default = {
321310
321887
  schemas: {
321311
321888
  path: {
321312
321889
  title: "Screenshot (simple)",
321890
+ $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 \u2014 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.",
321313
321891
  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.",
321314
321892
  type: "string",
321315
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321893
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321316
321894
  transform: [
321317
321895
  "trim"
321318
321896
  ]
@@ -321546,9 +322124,10 @@ var schemas_default = {
321546
322124
  },
321547
322125
  path: {
321548
322126
  title: "Screenshot (simple)",
322127
+ $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 \u2014 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.",
321549
322128
  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.",
321550
322129
  type: "string",
321551
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
322130
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
321552
322131
  transform: [
321553
322132
  "trim"
321554
322133
  ]
@@ -322022,9 +322601,10 @@ var schemas_default = {
322022
322601
  },
322023
322602
  path: {
322024
322603
  title: "Screenshot (simple)",
322604
+ $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 \u2014 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.",
322025
322605
  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.",
322026
322606
  type: "string",
322027
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
322607
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
322028
322608
  transform: [
322029
322609
  "trim"
322030
322610
  ]
@@ -322406,6 +322986,7 @@ var schemas_default = {
322406
322986
  "image.png",
322407
322987
  "static/images/image.png",
322408
322988
  "/User/manny/projects/doc-detective/static/images/image.png",
322989
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
322409
322990
  "https://example.com/static/images/image.png",
322410
322991
  {
322411
322992
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -324840,10 +325421,11 @@ var schemas_default = {
324840
325421
  },
324841
325422
  overwrite: {
324842
325423
  type: "string",
324843
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
325424
+ 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 \u2014 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`.",
324844
325425
  enum: [
324845
325426
  "true",
324846
- "false"
325427
+ "false",
325428
+ "aboveVariation"
324847
325429
  ]
324848
325430
  },
324849
325431
  name: {
@@ -324901,6 +325483,38 @@ var schemas_default = {
324901
325483
  }
324902
325484
  }
324903
325485
  ]
325486
+ },
325487
+ checkpoints: {
325488
+ title: "Recording checkpoints",
325489
+ 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.",
325490
+ anyOf: [
325491
+ {
325492
+ type: "boolean",
325493
+ title: "Recording checkpoints (boolean)",
325494
+ description: "If `true`, enables checkpoints with default settings."
325495
+ },
325496
+ {
325497
+ type: "object",
325498
+ title: "Recording checkpoints (detailed)",
325499
+ additionalProperties: false,
325500
+ properties: {
325501
+ maxVariation: {
325502
+ type: "number",
325503
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
325504
+ default: 0.05,
325505
+ minimum: 0,
325506
+ maximum: 1
325507
+ },
325508
+ directory: {
325509
+ type: "string",
325510
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
325511
+ transform: [
325512
+ "trim"
325513
+ ]
325514
+ }
325515
+ }
325516
+ }
325517
+ ]
324904
325518
  }
324905
325519
  },
324906
325520
  title: "Record (detailed)"
@@ -325162,10 +325776,11 @@ var schemas_default = {
325162
325776
  },
325163
325777
  overwrite: {
325164
325778
  type: "string",
325165
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
325779
+ 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 \u2014 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`.",
325166
325780
  enum: [
325167
325781
  "true",
325168
- "false"
325782
+ "false",
325783
+ "aboveVariation"
325169
325784
  ]
325170
325785
  },
325171
325786
  name: {
@@ -325223,6 +325838,38 @@ var schemas_default = {
325223
325838
  }
325224
325839
  }
325225
325840
  ]
325841
+ },
325842
+ checkpoints: {
325843
+ title: "Recording checkpoints",
325844
+ 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.",
325845
+ anyOf: [
325846
+ {
325847
+ type: "boolean",
325848
+ title: "Recording checkpoints (boolean)",
325849
+ description: "If `true`, enables checkpoints with default settings."
325850
+ },
325851
+ {
325852
+ type: "object",
325853
+ title: "Recording checkpoints (detailed)",
325854
+ additionalProperties: false,
325855
+ properties: {
325856
+ maxVariation: {
325857
+ type: "number",
325858
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
325859
+ default: 0.05,
325860
+ minimum: 0,
325861
+ maximum: 1
325862
+ },
325863
+ directory: {
325864
+ type: "string",
325865
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
325866
+ transform: [
325867
+ "trim"
325868
+ ]
325869
+ }
325870
+ }
325871
+ }
325872
+ ]
325226
325873
  }
325227
325874
  },
325228
325875
  title: "Record (detailed)"
@@ -325289,6 +325936,17 @@ var schemas_default = {
325289
325936
  path: "results.mp4",
325290
325937
  engine: "ffmpeg"
325291
325938
  },
325939
+ {
325940
+ path: "results.mp4",
325941
+ checkpoints: true
325942
+ },
325943
+ {
325944
+ path: "results.mp4",
325945
+ checkpoints: {
325946
+ maxVariation: 0.02,
325947
+ directory: "baselines/results"
325948
+ }
325949
+ },
325292
325950
  {
325293
325951
  path: "results.mp4",
325294
325952
  engine: {
@@ -365715,9 +366373,10 @@ var schemas_default = {
365715
366373
  anyOf: [
365716
366374
  {
365717
366375
  title: "Screenshot (simple)",
366376
+ $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 \u2014 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.",
365718
366377
  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.",
365719
366378
  type: "string",
365720
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366379
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
365721
366380
  transform: [
365722
366381
  "trim"
365723
366382
  ]
@@ -365951,9 +366610,10 @@ var schemas_default = {
365951
366610
  },
365952
366611
  path: {
365953
366612
  title: "Screenshot (simple)",
366613
+ $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 \u2014 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.",
365954
366614
  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.",
365955
366615
  type: "string",
365956
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366616
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
365957
366617
  transform: [
365958
366618
  "trim"
365959
366619
  ]
@@ -366211,9 +366871,10 @@ var schemas_default = {
366211
366871
  schemas: {
366212
366872
  path: {
366213
366873
  title: "Screenshot (simple)",
366874
+ $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 \u2014 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.",
366214
366875
  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.",
366215
366876
  type: "string",
366216
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366877
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366217
366878
  transform: [
366218
366879
  "trim"
366219
366880
  ]
@@ -366447,9 +367108,10 @@ var schemas_default = {
366447
367108
  },
366448
367109
  path: {
366449
367110
  title: "Screenshot (simple)",
367111
+ $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 \u2014 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.",
366450
367112
  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.",
366451
367113
  type: "string",
366452
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
367114
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366453
367115
  transform: [
366454
367116
  "trim"
366455
367117
  ]
@@ -366923,9 +367585,10 @@ var schemas_default = {
366923
367585
  },
366924
367586
  path: {
366925
367587
  title: "Screenshot (simple)",
367588
+ $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 \u2014 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.",
366926
367589
  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.",
366927
367590
  type: "string",
366928
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
367591
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
366929
367592
  transform: [
366930
367593
  "trim"
366931
367594
  ]
@@ -367307,6 +367970,7 @@ var schemas_default = {
367307
367970
  "image.png",
367308
367971
  "static/images/image.png",
367309
367972
  "/User/manny/projects/doc-detective/static/images/image.png",
367973
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
367310
367974
  "https://example.com/static/images/image.png",
367311
367975
  {
367312
367976
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -369741,10 +370405,11 @@ var schemas_default = {
369741
370405
  },
369742
370406
  overwrite: {
369743
370407
  type: "string",
369744
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
370408
+ 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 \u2014 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`.",
369745
370409
  enum: [
369746
370410
  "true",
369747
- "false"
370411
+ "false",
370412
+ "aboveVariation"
369748
370413
  ]
369749
370414
  },
369750
370415
  name: {
@@ -369802,6 +370467,38 @@ var schemas_default = {
369802
370467
  }
369803
370468
  }
369804
370469
  ]
370470
+ },
370471
+ checkpoints: {
370472
+ title: "Recording checkpoints",
370473
+ 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.",
370474
+ anyOf: [
370475
+ {
370476
+ type: "boolean",
370477
+ title: "Recording checkpoints (boolean)",
370478
+ description: "If `true`, enables checkpoints with default settings."
370479
+ },
370480
+ {
370481
+ type: "object",
370482
+ title: "Recording checkpoints (detailed)",
370483
+ additionalProperties: false,
370484
+ properties: {
370485
+ maxVariation: {
370486
+ type: "number",
370487
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
370488
+ default: 0.05,
370489
+ minimum: 0,
370490
+ maximum: 1
370491
+ },
370492
+ directory: {
370493
+ type: "string",
370494
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
370495
+ transform: [
370496
+ "trim"
370497
+ ]
370498
+ }
370499
+ }
370500
+ }
370501
+ ]
369805
370502
  }
369806
370503
  },
369807
370504
  title: "Record (detailed)"
@@ -370063,10 +370760,11 @@ var schemas_default = {
370063
370760
  },
370064
370761
  overwrite: {
370065
370762
  type: "string",
370066
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
370763
+ 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 \u2014 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`.",
370067
370764
  enum: [
370068
370765
  "true",
370069
- "false"
370766
+ "false",
370767
+ "aboveVariation"
370070
370768
  ]
370071
370769
  },
370072
370770
  name: {
@@ -370124,6 +370822,38 @@ var schemas_default = {
370124
370822
  }
370125
370823
  }
370126
370824
  ]
370825
+ },
370826
+ checkpoints: {
370827
+ title: "Recording checkpoints",
370828
+ 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.",
370829
+ anyOf: [
370830
+ {
370831
+ type: "boolean",
370832
+ title: "Recording checkpoints (boolean)",
370833
+ description: "If `true`, enables checkpoints with default settings."
370834
+ },
370835
+ {
370836
+ type: "object",
370837
+ title: "Recording checkpoints (detailed)",
370838
+ additionalProperties: false,
370839
+ properties: {
370840
+ maxVariation: {
370841
+ type: "number",
370842
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
370843
+ default: 0.05,
370844
+ minimum: 0,
370845
+ maximum: 1
370846
+ },
370847
+ directory: {
370848
+ type: "string",
370849
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
370850
+ transform: [
370851
+ "trim"
370852
+ ]
370853
+ }
370854
+ }
370855
+ }
370856
+ ]
370127
370857
  }
370128
370858
  },
370129
370859
  title: "Record (detailed)"
@@ -370190,6 +370920,17 @@ var schemas_default = {
370190
370920
  path: "results.mp4",
370191
370921
  engine: "ffmpeg"
370192
370922
  },
370923
+ {
370924
+ path: "results.mp4",
370925
+ checkpoints: true
370926
+ },
370927
+ {
370928
+ path: "results.mp4",
370929
+ checkpoints: {
370930
+ maxVariation: 0.02,
370931
+ directory: "baselines/results"
370932
+ }
370933
+ },
370193
370934
  {
370194
370935
  path: "results.mp4",
370195
370936
  engine: {
@@ -385726,9 +386467,10 @@ var schemas_default = {
385726
386467
  anyOf: [
385727
386468
  {
385728
386469
  title: "Screenshot (simple)",
386470
+ $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 \u2014 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.",
385729
386471
  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.",
385730
386472
  type: "string",
385731
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386473
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
385732
386474
  transform: [
385733
386475
  "trim"
385734
386476
  ]
@@ -385962,9 +386704,10 @@ var schemas_default = {
385962
386704
  },
385963
386705
  path: {
385964
386706
  title: "Screenshot (simple)",
386707
+ $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 \u2014 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.",
385965
386708
  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.",
385966
386709
  type: "string",
385967
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386710
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
385968
386711
  transform: [
385969
386712
  "trim"
385970
386713
  ]
@@ -386222,9 +386965,10 @@ var schemas_default = {
386222
386965
  schemas: {
386223
386966
  path: {
386224
386967
  title: "Screenshot (simple)",
386968
+ $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 \u2014 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.",
386225
386969
  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.",
386226
386970
  type: "string",
386227
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386971
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386228
386972
  transform: [
386229
386973
  "trim"
386230
386974
  ]
@@ -386458,9 +387202,10 @@ var schemas_default = {
386458
387202
  },
386459
387203
  path: {
386460
387204
  title: "Screenshot (simple)",
387205
+ $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 \u2014 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.",
386461
387206
  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.",
386462
387207
  type: "string",
386463
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
387208
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386464
387209
  transform: [
386465
387210
  "trim"
386466
387211
  ]
@@ -386934,9 +387679,10 @@ var schemas_default = {
386934
387679
  },
386935
387680
  path: {
386936
387681
  title: "Screenshot (simple)",
387682
+ $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 \u2014 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.",
386937
387683
  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.",
386938
387684
  type: "string",
386939
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
387685
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
386940
387686
  transform: [
386941
387687
  "trim"
386942
387688
  ]
@@ -387318,6 +388064,7 @@ var schemas_default = {
387318
388064
  "image.png",
387319
388065
  "static/images/image.png",
387320
388066
  "/User/manny/projects/doc-detective/static/images/image.png",
388067
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
387321
388068
  "https://example.com/static/images/image.png",
387322
388069
  {
387323
388070
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -416901,9 +417648,10 @@ var schemas_default = {
416901
417648
  anyOf: [
416902
417649
  {
416903
417650
  title: "Screenshot (simple)",
417651
+ $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 \u2014 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.",
416904
417652
  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.",
416905
417653
  type: "string",
416906
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417654
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
416907
417655
  transform: [
416908
417656
  "trim"
416909
417657
  ]
@@ -417137,9 +417885,10 @@ var schemas_default = {
417137
417885
  },
417138
417886
  path: {
417139
417887
  title: "Screenshot (simple)",
417888
+ $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 \u2014 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.",
417140
417889
  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.",
417141
417890
  type: "string",
417142
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417891
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417143
417892
  transform: [
417144
417893
  "trim"
417145
417894
  ]
@@ -417397,9 +418146,10 @@ var schemas_default = {
417397
418146
  schemas: {
417398
418147
  path: {
417399
418148
  title: "Screenshot (simple)",
418149
+ $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 \u2014 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.",
417400
418150
  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.",
417401
418151
  type: "string",
417402
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418152
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417403
418153
  transform: [
417404
418154
  "trim"
417405
418155
  ]
@@ -417633,9 +418383,10 @@ var schemas_default = {
417633
418383
  },
417634
418384
  path: {
417635
418385
  title: "Screenshot (simple)",
418386
+ $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 \u2014 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.",
417636
418387
  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.",
417637
418388
  type: "string",
417638
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418389
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
417639
418390
  transform: [
417640
418391
  "trim"
417641
418392
  ]
@@ -418109,9 +418860,10 @@ var schemas_default = {
418109
418860
  },
418110
418861
  path: {
418111
418862
  title: "Screenshot (simple)",
418863
+ $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 \u2014 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.",
418112
418864
  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.",
418113
418865
  type: "string",
418114
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418866
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
418115
418867
  transform: [
418116
418868
  "trim"
418117
418869
  ]
@@ -418493,6 +419245,7 @@ var schemas_default = {
418493
419245
  "image.png",
418494
419246
  "static/images/image.png",
418495
419247
  "/User/manny/projects/doc-detective/static/images/image.png",
419248
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
418496
419249
  "https://example.com/static/images/image.png",
418497
419250
  {
418498
419251
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -420927,10 +421680,11 @@ var schemas_default = {
420927
421680
  },
420928
421681
  overwrite: {
420929
421682
  type: "string",
420930
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
421683
+ 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 \u2014 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`.",
420931
421684
  enum: [
420932
421685
  "true",
420933
- "false"
421686
+ "false",
421687
+ "aboveVariation"
420934
421688
  ]
420935
421689
  },
420936
421690
  name: {
@@ -420988,6 +421742,38 @@ var schemas_default = {
420988
421742
  }
420989
421743
  }
420990
421744
  ]
421745
+ },
421746
+ checkpoints: {
421747
+ title: "Recording checkpoints",
421748
+ 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.",
421749
+ anyOf: [
421750
+ {
421751
+ type: "boolean",
421752
+ title: "Recording checkpoints (boolean)",
421753
+ description: "If `true`, enables checkpoints with default settings."
421754
+ },
421755
+ {
421756
+ type: "object",
421757
+ title: "Recording checkpoints (detailed)",
421758
+ additionalProperties: false,
421759
+ properties: {
421760
+ maxVariation: {
421761
+ type: "number",
421762
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
421763
+ default: 0.05,
421764
+ minimum: 0,
421765
+ maximum: 1
421766
+ },
421767
+ directory: {
421768
+ type: "string",
421769
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
421770
+ transform: [
421771
+ "trim"
421772
+ ]
421773
+ }
421774
+ }
421775
+ }
421776
+ ]
420991
421777
  }
420992
421778
  },
420993
421779
  title: "Record (detailed)"
@@ -421249,10 +422035,11 @@ var schemas_default = {
421249
422035
  },
421250
422036
  overwrite: {
421251
422037
  type: "string",
421252
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
422038
+ 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 \u2014 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`.",
421253
422039
  enum: [
421254
422040
  "true",
421255
- "false"
422041
+ "false",
422042
+ "aboveVariation"
421256
422043
  ]
421257
422044
  },
421258
422045
  name: {
@@ -421310,6 +422097,38 @@ var schemas_default = {
421310
422097
  }
421311
422098
  }
421312
422099
  ]
422100
+ },
422101
+ checkpoints: {
422102
+ title: "Recording checkpoints",
422103
+ 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.",
422104
+ anyOf: [
422105
+ {
422106
+ type: "boolean",
422107
+ title: "Recording checkpoints (boolean)",
422108
+ description: "If `true`, enables checkpoints with default settings."
422109
+ },
422110
+ {
422111
+ type: "object",
422112
+ title: "Recording checkpoints (detailed)",
422113
+ additionalProperties: false,
422114
+ properties: {
422115
+ maxVariation: {
422116
+ type: "number",
422117
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
422118
+ default: 0.05,
422119
+ minimum: 0,
422120
+ maximum: 1
422121
+ },
422122
+ directory: {
422123
+ type: "string",
422124
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
422125
+ transform: [
422126
+ "trim"
422127
+ ]
422128
+ }
422129
+ }
422130
+ }
422131
+ ]
421313
422132
  }
421314
422133
  },
421315
422134
  title: "Record (detailed)"
@@ -421376,6 +422195,17 @@ var schemas_default = {
421376
422195
  path: "results.mp4",
421377
422196
  engine: "ffmpeg"
421378
422197
  },
422198
+ {
422199
+ path: "results.mp4",
422200
+ checkpoints: true
422201
+ },
422202
+ {
422203
+ path: "results.mp4",
422204
+ checkpoints: {
422205
+ maxVariation: 0.02,
422206
+ directory: "baselines/results"
422207
+ }
422208
+ },
421379
422209
  {
421380
422210
  path: "results.mp4",
421381
422211
  engine: {
@@ -461802,9 +462632,10 @@ var schemas_default = {
461802
462632
  anyOf: [
461803
462633
  {
461804
462634
  title: "Screenshot (simple)",
462635
+ $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 \u2014 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.",
461805
462636
  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.",
461806
462637
  type: "string",
461807
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462638
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
461808
462639
  transform: [
461809
462640
  "trim"
461810
462641
  ]
@@ -462038,9 +462869,10 @@ var schemas_default = {
462038
462869
  },
462039
462870
  path: {
462040
462871
  title: "Screenshot (simple)",
462872
+ $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 \u2014 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.",
462041
462873
  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.",
462042
462874
  type: "string",
462043
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462875
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462044
462876
  transform: [
462045
462877
  "trim"
462046
462878
  ]
@@ -462298,9 +463130,10 @@ var schemas_default = {
462298
463130
  schemas: {
462299
463131
  path: {
462300
463132
  title: "Screenshot (simple)",
463133
+ $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 \u2014 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.",
462301
463134
  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.",
462302
463135
  type: "string",
462303
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463136
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462304
463137
  transform: [
462305
463138
  "trim"
462306
463139
  ]
@@ -462534,9 +463367,10 @@ var schemas_default = {
462534
463367
  },
462535
463368
  path: {
462536
463369
  title: "Screenshot (simple)",
463370
+ $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 \u2014 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.",
462537
463371
  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.",
462538
463372
  type: "string",
462539
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463373
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
462540
463374
  transform: [
462541
463375
  "trim"
462542
463376
  ]
@@ -463010,9 +463844,10 @@ var schemas_default = {
463010
463844
  },
463011
463845
  path: {
463012
463846
  title: "Screenshot (simple)",
463847
+ $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 \u2014 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.",
463013
463848
  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.",
463014
463849
  type: "string",
463015
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463850
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
463016
463851
  transform: [
463017
463852
  "trim"
463018
463853
  ]
@@ -463394,6 +464229,7 @@ var schemas_default = {
463394
464229
  "image.png",
463395
464230
  "static/images/image.png",
463396
464231
  "/User/manny/projects/doc-detective/static/images/image.png",
464232
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
463397
464233
  "https://example.com/static/images/image.png",
463398
464234
  {
463399
464235
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -465828,10 +466664,11 @@ var schemas_default = {
465828
466664
  },
465829
466665
  overwrite: {
465830
466666
  type: "string",
465831
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
466667
+ 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 \u2014 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`.",
465832
466668
  enum: [
465833
466669
  "true",
465834
- "false"
466670
+ "false",
466671
+ "aboveVariation"
465835
466672
  ]
465836
466673
  },
465837
466674
  name: {
@@ -465889,6 +466726,38 @@ var schemas_default = {
465889
466726
  }
465890
466727
  }
465891
466728
  ]
466729
+ },
466730
+ checkpoints: {
466731
+ title: "Recording checkpoints",
466732
+ 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.",
466733
+ anyOf: [
466734
+ {
466735
+ type: "boolean",
466736
+ title: "Recording checkpoints (boolean)",
466737
+ description: "If `true`, enables checkpoints with default settings."
466738
+ },
466739
+ {
466740
+ type: "object",
466741
+ title: "Recording checkpoints (detailed)",
466742
+ additionalProperties: false,
466743
+ properties: {
466744
+ maxVariation: {
466745
+ type: "number",
466746
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
466747
+ default: 0.05,
466748
+ minimum: 0,
466749
+ maximum: 1
466750
+ },
466751
+ directory: {
466752
+ type: "string",
466753
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
466754
+ transform: [
466755
+ "trim"
466756
+ ]
466757
+ }
466758
+ }
466759
+ }
466760
+ ]
465892
466761
  }
465893
466762
  },
465894
466763
  title: "Record (detailed)"
@@ -466150,10 +467019,11 @@ var schemas_default = {
466150
467019
  },
466151
467020
  overwrite: {
466152
467021
  type: "string",
466153
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
467022
+ 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 \u2014 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`.",
466154
467023
  enum: [
466155
467024
  "true",
466156
- "false"
467025
+ "false",
467026
+ "aboveVariation"
466157
467027
  ]
466158
467028
  },
466159
467029
  name: {
@@ -466211,6 +467081,38 @@ var schemas_default = {
466211
467081
  }
466212
467082
  }
466213
467083
  ]
467084
+ },
467085
+ checkpoints: {
467086
+ title: "Recording checkpoints",
467087
+ 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.",
467088
+ anyOf: [
467089
+ {
467090
+ type: "boolean",
467091
+ title: "Recording checkpoints (boolean)",
467092
+ description: "If `true`, enables checkpoints with default settings."
467093
+ },
467094
+ {
467095
+ type: "object",
467096
+ title: "Recording checkpoints (detailed)",
467097
+ additionalProperties: false,
467098
+ properties: {
467099
+ maxVariation: {
467100
+ type: "number",
467101
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
467102
+ default: 0.05,
467103
+ minimum: 0,
467104
+ maximum: 1
467105
+ },
467106
+ directory: {
467107
+ type: "string",
467108
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
467109
+ transform: [
467110
+ "trim"
467111
+ ]
467112
+ }
467113
+ }
467114
+ }
467115
+ ]
466214
467116
  }
466215
467117
  },
466216
467118
  title: "Record (detailed)"
@@ -466277,6 +467179,17 @@ var schemas_default = {
466277
467179
  path: "results.mp4",
466278
467180
  engine: "ffmpeg"
466279
467181
  },
467182
+ {
467183
+ path: "results.mp4",
467184
+ checkpoints: true
467185
+ },
467186
+ {
467187
+ path: "results.mp4",
467188
+ checkpoints: {
467189
+ maxVariation: 0.02,
467190
+ directory: "baselines/results"
467191
+ }
467192
+ },
466280
467193
  {
466281
467194
  path: "results.mp4",
466282
467195
  engine: {
@@ -508395,9 +509308,10 @@ var schemas_default = {
508395
509308
  anyOf: [
508396
509309
  {
508397
509310
  title: "Screenshot (simple)",
509311
+ $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 \u2014 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.",
508398
509312
  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.",
508399
509313
  type: "string",
508400
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509314
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
508401
509315
  transform: [
508402
509316
  "trim"
508403
509317
  ]
@@ -508631,9 +509545,10 @@ var schemas_default = {
508631
509545
  },
508632
509546
  path: {
508633
509547
  title: "Screenshot (simple)",
509548
+ $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 \u2014 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.",
508634
509549
  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.",
508635
509550
  type: "string",
508636
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509551
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
508637
509552
  transform: [
508638
509553
  "trim"
508639
509554
  ]
@@ -508891,9 +509806,10 @@ var schemas_default = {
508891
509806
  schemas: {
508892
509807
  path: {
508893
509808
  title: "Screenshot (simple)",
509809
+ $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 \u2014 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.",
508894
509810
  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.",
508895
509811
  type: "string",
508896
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509812
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
508897
509813
  transform: [
508898
509814
  "trim"
508899
509815
  ]
@@ -509127,9 +510043,10 @@ var schemas_default = {
509127
510043
  },
509128
510044
  path: {
509129
510045
  title: "Screenshot (simple)",
510046
+ $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 \u2014 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.",
509130
510047
  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.",
509131
510048
  type: "string",
509132
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
510049
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509133
510050
  transform: [
509134
510051
  "trim"
509135
510052
  ]
@@ -509603,9 +510520,10 @@ var schemas_default = {
509603
510520
  },
509604
510521
  path: {
509605
510522
  title: "Screenshot (simple)",
510523
+ $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 \u2014 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.",
509606
510524
  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.",
509607
510525
  type: "string",
509608
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
510526
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
509609
510527
  transform: [
509610
510528
  "trim"
509611
510529
  ]
@@ -509987,6 +510905,7 @@ var schemas_default = {
509987
510905
  "image.png",
509988
510906
  "static/images/image.png",
509989
510907
  "/User/manny/projects/doc-detective/static/images/image.png",
510908
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
509990
510909
  "https://example.com/static/images/image.png",
509991
510910
  {
509992
510911
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -512421,10 +513340,11 @@ var schemas_default = {
512421
513340
  },
512422
513341
  overwrite: {
512423
513342
  type: "string",
512424
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
513343
+ 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 \u2014 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`.",
512425
513344
  enum: [
512426
513345
  "true",
512427
- "false"
513346
+ "false",
513347
+ "aboveVariation"
512428
513348
  ]
512429
513349
  },
512430
513350
  name: {
@@ -512482,6 +513402,38 @@ var schemas_default = {
512482
513402
  }
512483
513403
  }
512484
513404
  ]
513405
+ },
513406
+ checkpoints: {
513407
+ title: "Recording checkpoints",
513408
+ 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.",
513409
+ anyOf: [
513410
+ {
513411
+ type: "boolean",
513412
+ title: "Recording checkpoints (boolean)",
513413
+ description: "If `true`, enables checkpoints with default settings."
513414
+ },
513415
+ {
513416
+ type: "object",
513417
+ title: "Recording checkpoints (detailed)",
513418
+ additionalProperties: false,
513419
+ properties: {
513420
+ maxVariation: {
513421
+ type: "number",
513422
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
513423
+ default: 0.05,
513424
+ minimum: 0,
513425
+ maximum: 1
513426
+ },
513427
+ directory: {
513428
+ type: "string",
513429
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
513430
+ transform: [
513431
+ "trim"
513432
+ ]
513433
+ }
513434
+ }
513435
+ }
513436
+ ]
512485
513437
  }
512486
513438
  },
512487
513439
  title: "Record (detailed)"
@@ -512743,10 +513695,11 @@ var schemas_default = {
512743
513695
  },
512744
513696
  overwrite: {
512745
513697
  type: "string",
512746
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
513698
+ 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 \u2014 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`.",
512747
513699
  enum: [
512748
513700
  "true",
512749
- "false"
513701
+ "false",
513702
+ "aboveVariation"
512750
513703
  ]
512751
513704
  },
512752
513705
  name: {
@@ -512804,6 +513757,38 @@ var schemas_default = {
512804
513757
  }
512805
513758
  }
512806
513759
  ]
513760
+ },
513761
+ checkpoints: {
513762
+ title: "Recording checkpoints",
513763
+ 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.",
513764
+ anyOf: [
513765
+ {
513766
+ type: "boolean",
513767
+ title: "Recording checkpoints (boolean)",
513768
+ description: "If `true`, enables checkpoints with default settings."
513769
+ },
513770
+ {
513771
+ type: "object",
513772
+ title: "Recording checkpoints (detailed)",
513773
+ additionalProperties: false,
513774
+ properties: {
513775
+ maxVariation: {
513776
+ type: "number",
513777
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
513778
+ default: 0.05,
513779
+ minimum: 0,
513780
+ maximum: 1
513781
+ },
513782
+ directory: {
513783
+ type: "string",
513784
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
513785
+ transform: [
513786
+ "trim"
513787
+ ]
513788
+ }
513789
+ }
513790
+ }
513791
+ ]
512807
513792
  }
512808
513793
  },
512809
513794
  title: "Record (detailed)"
@@ -512870,6 +513855,17 @@ var schemas_default = {
512870
513855
  path: "results.mp4",
512871
513856
  engine: "ffmpeg"
512872
513857
  },
513858
+ {
513859
+ path: "results.mp4",
513860
+ checkpoints: true
513861
+ },
513862
+ {
513863
+ path: "results.mp4",
513864
+ checkpoints: {
513865
+ maxVariation: 0.02,
513866
+ directory: "baselines/results"
513867
+ }
513868
+ },
512873
513869
  {
512874
513870
  path: "results.mp4",
512875
513871
  engine: {
@@ -556641,9 +557637,10 @@ var schemas_default = {
556641
557637
  anyOf: [
556642
557638
  {
556643
557639
  title: "Screenshot (simple)",
557640
+ $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 \u2014 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.",
556644
557641
  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.",
556645
557642
  type: "string",
556646
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557643
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
556647
557644
  transform: [
556648
557645
  "trim"
556649
557646
  ]
@@ -556877,9 +557874,10 @@ var schemas_default = {
556877
557874
  },
556878
557875
  path: {
556879
557876
  title: "Screenshot (simple)",
557877
+ $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 \u2014 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.",
556880
557878
  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.",
556881
557879
  type: "string",
556882
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557880
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
556883
557881
  transform: [
556884
557882
  "trim"
556885
557883
  ]
@@ -557137,9 +558135,10 @@ var schemas_default = {
557137
558135
  schemas: {
557138
558136
  path: {
557139
558137
  title: "Screenshot (simple)",
558138
+ $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 \u2014 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.",
557140
558139
  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.",
557141
558140
  type: "string",
557142
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
558141
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557143
558142
  transform: [
557144
558143
  "trim"
557145
558144
  ]
@@ -557373,9 +558372,10 @@ var schemas_default = {
557373
558372
  },
557374
558373
  path: {
557375
558374
  title: "Screenshot (simple)",
558375
+ $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 \u2014 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.",
557376
558376
  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.",
557377
558377
  type: "string",
557378
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
558378
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557379
558379
  transform: [
557380
558380
  "trim"
557381
558381
  ]
@@ -557849,9 +558849,10 @@ var schemas_default = {
557849
558849
  },
557850
558850
  path: {
557851
558851
  title: "Screenshot (simple)",
558852
+ $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 \u2014 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.",
557852
558853
  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.",
557853
558854
  type: "string",
557854
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
558855
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
557855
558856
  transform: [
557856
558857
  "trim"
557857
558858
  ]
@@ -558233,6 +559234,7 @@ var schemas_default = {
558233
559234
  "image.png",
558234
559235
  "static/images/image.png",
558235
559236
  "/User/manny/projects/doc-detective/static/images/image.png",
559237
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
558236
559238
  "https://example.com/static/images/image.png",
558237
559239
  {
558238
559240
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -560667,10 +561669,11 @@ var schemas_default = {
560667
561669
  },
560668
561670
  overwrite: {
560669
561671
  type: "string",
560670
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
561672
+ 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 \u2014 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`.",
560671
561673
  enum: [
560672
561674
  "true",
560673
- "false"
561675
+ "false",
561676
+ "aboveVariation"
560674
561677
  ]
560675
561678
  },
560676
561679
  name: {
@@ -560728,6 +561731,38 @@ var schemas_default = {
560728
561731
  }
560729
561732
  }
560730
561733
  ]
561734
+ },
561735
+ checkpoints: {
561736
+ title: "Recording checkpoints",
561737
+ 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.",
561738
+ anyOf: [
561739
+ {
561740
+ type: "boolean",
561741
+ title: "Recording checkpoints (boolean)",
561742
+ description: "If `true`, enables checkpoints with default settings."
561743
+ },
561744
+ {
561745
+ type: "object",
561746
+ title: "Recording checkpoints (detailed)",
561747
+ additionalProperties: false,
561748
+ properties: {
561749
+ maxVariation: {
561750
+ type: "number",
561751
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
561752
+ default: 0.05,
561753
+ minimum: 0,
561754
+ maximum: 1
561755
+ },
561756
+ directory: {
561757
+ type: "string",
561758
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
561759
+ transform: [
561760
+ "trim"
561761
+ ]
561762
+ }
561763
+ }
561764
+ }
561765
+ ]
560731
561766
  }
560732
561767
  },
560733
561768
  title: "Record (detailed)"
@@ -560989,10 +562024,11 @@ var schemas_default = {
560989
562024
  },
560990
562025
  overwrite: {
560991
562026
  type: "string",
560992
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
562027
+ 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 \u2014 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`.",
560993
562028
  enum: [
560994
562029
  "true",
560995
- "false"
562030
+ "false",
562031
+ "aboveVariation"
560996
562032
  ]
560997
562033
  },
560998
562034
  name: {
@@ -561050,6 +562086,38 @@ var schemas_default = {
561050
562086
  }
561051
562087
  }
561052
562088
  ]
562089
+ },
562090
+ checkpoints: {
562091
+ title: "Recording checkpoints",
562092
+ 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.",
562093
+ anyOf: [
562094
+ {
562095
+ type: "boolean",
562096
+ title: "Recording checkpoints (boolean)",
562097
+ description: "If `true`, enables checkpoints with default settings."
562098
+ },
562099
+ {
562100
+ type: "object",
562101
+ title: "Recording checkpoints (detailed)",
562102
+ additionalProperties: false,
562103
+ properties: {
562104
+ maxVariation: {
562105
+ type: "number",
562106
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
562107
+ default: 0.05,
562108
+ minimum: 0,
562109
+ maximum: 1
562110
+ },
562111
+ directory: {
562112
+ type: "string",
562113
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
562114
+ transform: [
562115
+ "trim"
562116
+ ]
562117
+ }
562118
+ }
562119
+ }
562120
+ ]
561053
562121
  }
561054
562122
  },
561055
562123
  title: "Record (detailed)"
@@ -561116,6 +562184,17 @@ var schemas_default = {
561116
562184
  path: "results.mp4",
561117
562185
  engine: "ffmpeg"
561118
562186
  },
562187
+ {
562188
+ path: "results.mp4",
562189
+ checkpoints: true
562190
+ },
562191
+ {
562192
+ path: "results.mp4",
562193
+ checkpoints: {
562194
+ maxVariation: 0.02,
562195
+ directory: "baselines/results"
562196
+ }
562197
+ },
561119
562198
  {
561120
562199
  path: "results.mp4",
561121
562200
  engine: {
@@ -601542,9 +602621,10 @@ var schemas_default = {
601542
602621
  anyOf: [
601543
602622
  {
601544
602623
  title: "Screenshot (simple)",
602624
+ $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 \u2014 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.",
601545
602625
  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.",
601546
602626
  type: "string",
601547
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602627
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
601548
602628
  transform: [
601549
602629
  "trim"
601550
602630
  ]
@@ -601778,9 +602858,10 @@ var schemas_default = {
601778
602858
  },
601779
602859
  path: {
601780
602860
  title: "Screenshot (simple)",
602861
+ $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 \u2014 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.",
601781
602862
  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.",
601782
602863
  type: "string",
601783
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602864
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
601784
602865
  transform: [
601785
602866
  "trim"
601786
602867
  ]
@@ -602038,9 +603119,10 @@ var schemas_default = {
602038
603119
  schemas: {
602039
603120
  path: {
602040
603121
  title: "Screenshot (simple)",
603122
+ $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 \u2014 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.",
602041
603123
  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.",
602042
603124
  type: "string",
602043
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
603125
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602044
603126
  transform: [
602045
603127
  "trim"
602046
603128
  ]
@@ -602274,9 +603356,10 @@ var schemas_default = {
602274
603356
  },
602275
603357
  path: {
602276
603358
  title: "Screenshot (simple)",
603359
+ $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 \u2014 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.",
602277
603360
  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.",
602278
603361
  type: "string",
602279
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
603362
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602280
603363
  transform: [
602281
603364
  "trim"
602282
603365
  ]
@@ -602750,9 +603833,10 @@ var schemas_default = {
602750
603833
  },
602751
603834
  path: {
602752
603835
  title: "Screenshot (simple)",
603836
+ $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 \u2014 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.",
602753
603837
  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.",
602754
603838
  type: "string",
602755
- pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
603839
+ pattern: "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
602756
603840
  transform: [
602757
603841
  "trim"
602758
603842
  ]
@@ -603134,6 +604218,7 @@ var schemas_default = {
603134
604218
  "image.png",
603135
604219
  "static/images/image.png",
603136
604220
  "/User/manny/projects/doc-detective/static/images/image.png",
604221
+ "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
603137
604222
  "https://example.com/static/images/image.png",
603138
604223
  {
603139
604224
  path: "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -605568,10 +606653,11 @@ var schemas_default = {
605568
606653
  },
605569
606654
  overwrite: {
605570
606655
  type: "string",
605571
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
606656
+ 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 \u2014 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`.",
605572
606657
  enum: [
605573
606658
  "true",
605574
- "false"
606659
+ "false",
606660
+ "aboveVariation"
605575
606661
  ]
605576
606662
  },
605577
606663
  name: {
@@ -605629,6 +606715,38 @@ var schemas_default = {
605629
606715
  }
605630
606716
  }
605631
606717
  ]
606718
+ },
606719
+ checkpoints: {
606720
+ title: "Recording checkpoints",
606721
+ 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.",
606722
+ anyOf: [
606723
+ {
606724
+ type: "boolean",
606725
+ title: "Recording checkpoints (boolean)",
606726
+ description: "If `true`, enables checkpoints with default settings."
606727
+ },
606728
+ {
606729
+ type: "object",
606730
+ title: "Recording checkpoints (detailed)",
606731
+ additionalProperties: false,
606732
+ properties: {
606733
+ maxVariation: {
606734
+ type: "number",
606735
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
606736
+ default: 0.05,
606737
+ minimum: 0,
606738
+ maximum: 1
606739
+ },
606740
+ directory: {
606741
+ type: "string",
606742
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
606743
+ transform: [
606744
+ "trim"
606745
+ ]
606746
+ }
606747
+ }
606748
+ }
606749
+ ]
605632
606750
  }
605633
606751
  },
605634
606752
  title: "Record (detailed)"
@@ -605890,10 +607008,11 @@ var schemas_default = {
605890
607008
  },
605891
607009
  overwrite: {
605892
607010
  type: "string",
605893
- description: "If `true`, overwrites the existing recording at `path` if it exists.",
607011
+ 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 \u2014 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`.",
605894
607012
  enum: [
605895
607013
  "true",
605896
- "false"
607014
+ "false",
607015
+ "aboveVariation"
605897
607016
  ]
605898
607017
  },
605899
607018
  name: {
@@ -605951,6 +607070,38 @@ var schemas_default = {
605951
607070
  }
605952
607071
  }
605953
607072
  ]
607073
+ },
607074
+ checkpoints: {
607075
+ title: "Recording checkpoints",
607076
+ 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.",
607077
+ anyOf: [
607078
+ {
607079
+ type: "boolean",
607080
+ title: "Recording checkpoints (boolean)",
607081
+ description: "If `true`, enables checkpoints with default settings."
607082
+ },
607083
+ {
607084
+ type: "object",
607085
+ title: "Recording checkpoints (detailed)",
607086
+ additionalProperties: false,
607087
+ properties: {
607088
+ maxVariation: {
607089
+ type: "number",
607090
+ description: "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
607091
+ default: 0.05,
607092
+ minimum: 0,
607093
+ maximum: 1
607094
+ },
607095
+ directory: {
607096
+ type: "string",
607097
+ description: "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
607098
+ transform: [
607099
+ "trim"
607100
+ ]
607101
+ }
607102
+ }
607103
+ }
607104
+ ]
605954
607105
  }
605955
607106
  },
605956
607107
  title: "Record (detailed)"
@@ -606017,6 +607168,17 @@ var schemas_default = {
606017
607168
  path: "results.mp4",
606018
607169
  engine: "ffmpeg"
606019
607170
  },
607171
+ {
607172
+ path: "results.mp4",
607173
+ checkpoints: true
607174
+ },
607175
+ {
607176
+ path: "results.mp4",
607177
+ checkpoints: {
607178
+ maxVariation: 0.02,
607179
+ directory: "baselines/results"
607180
+ }
607181
+ },
606020
607182
  {
606021
607183
  path: "results.mp4",
606022
607184
  engine: {