@vosjs/cli 0.77.1 → 0.79.0

package/schema/actions.schema.json

@@ -80,6 +80,12 @@
         }
       }
     },
+    "ready": {
+      "type": "string",
+      "enum": ["dom", "networkidle"],
+      "default": "dom",
+      "description": "When the first page counts as ready for step 1. dom: after load, once the page has made no DOM change for 800 ms, at most 8 s. networkidle: once the network has gone quiet, at most 45 s, which a page holding a socket open or an analytics beacon never does. The same mode opens a setup goto, the page after a setup, and an await's reload. `--ready` overrides. The done event's `ready` says how the first load settled ({ mode, ms, capped }); `navTimeout` is true only when networkidle was asked for and never came."
+    },
     "mask": {
       "type": "array",
       "description": "Hidden BEFORE the first frame is captured and kept hidden across navigations and re-renders: what a signed-in account shows that must not ship. The real value is never in a frame, never in the recording, never pushed. `vos record` reports what it still sees afterwards (meta.exposures), and a mask whose selector reached nothing fails --strict.",
@@ -104,6 +110,11 @@
         }
       }
     },
+    "settle": {
+      "type": "boolean",
+      "default": false,
+      "description": "every gesture step waits on the app after it (a step's own settle overrides): a canvas that falls behind under load finishes the last stroke before the next one starts"
+    },
     "steps": {
       "type": "array",
       "minItems": 1,
@@ -140,14 +151,24 @@
           },
           {
             "type": "object",
-            "required": ["do", "selector"],
+            "required": ["do"],
             "additionalProperties": false,
             "properties": {
               "do": {
                 "const": "hover"
               },
               "selector": {
-                "type": "string"
+                "type": "string",
+                "description": "the element whose centre the pointer goes to; or x and y instead"
+              },
+              "x": {
+                "type": "number",
+                "minimum": 0,
+                "description": "with y: a viewport point in CSS px, for a spot no selector names (a place on a canvas); takes no selector"
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0
               },
               "ms": {
                 "type": "number",
@@ -155,6 +176,10 @@
                 "default": 700,
                 "description": "Dwell — parked cursor becomes a zoom signal."
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -170,11 +195,33 @@
                 "minLength": 1,
                 "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["selector"],
+                "not": {
+                  "anyOf": [
+                    {
+                      "required": ["x"]
+                    },
+                    {
+                      "required": ["y"]
+                    }
+                  ]
+                }
+              },
+              {
+                "required": ["x", "y"],
+                "not": {
+                  "required": ["selector"]
+                }
+              }
+            ],
+            "description": "Rest the pointer on an element's centre (selector) or on a viewport point (x, y); ms is the dwell, a zoom signal."
           },
           {
             "type": "object",
-            "required": ["do", "selector"],
+            "required": ["do"],
             "additionalProperties": false,
             "properties": {
               "do": {
@@ -186,7 +233,42 @@
                 "description": "the read after the press, ms (default 150), held from the page's last visual change: the recorder watches the screencast and pays the settle itself (a change within 400 ms says the page is answering, 250 ms of quiet says it settled, 1.2 s bounds a page that never stops), so the same ms reads the same on every run. Size it as a reading beat, about 1000 after a navigation and 600 after a control, never padded for a slow page."
               },
               "selector": {
-                "type": "string"
+                "type": "string",
+                "description": "the element whose centre the pointer goes to; or x and y instead"
+              },
+              "x": {
+                "type": "number",
+                "minimum": 0,
+                "description": "with y: a viewport point in CSS px, for a spot no selector names (a place on a canvas); takes no selector"
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0
+              },
+              "count": {
+                "type": "integer",
+                "enum": [1, 2, 3],
+                "default": 1,
+                "description": "2 is a real double click, 3 a triple click: that many presses inside the platform's double-click interval, each carrying its click count; every press is a down and an up on the cursor track"
+              },
+              "button": {
+                "type": "string",
+                "enum": ["left", "right", "middle"],
+                "default": "left",
+                "description": "the button pressed: right opens a context menu"
+              },
+              "modifiers": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "enum": ["Alt", "Shift", "Meta", "Control", "Mod"]
+                },
+                "description": "held for the press (a Shift-click adds to the selection) and released after it, whatever happens; Mod is Meta on macOS, Control elsewhere"
+              },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
               },
               "id": {
                 "type": "string",
@@ -202,8 +284,34 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              },
+              "guard": {
+                "type": "string",
+                "enum": ["spend"],
+                "description": "the step costs something real (credits, a purchase, a message sent): `vos record --dry-run` hovers it and never presses it, and `vos record` presses it only with `--confirm <id>`, refusing before any capture otherwise. Needs an id. A hosted take refuses a guarded step"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["selector"],
+                "not": {
+                  "anyOf": [
+                    {
+                      "required": ["x"]
+                    },
+                    {
+                      "required": ["y"]
+                    }
+                  ]
+                }
+              },
+              {
+                "required": ["x", "y"],
+                "not": {
+                  "required": ["selector"]
+                }
+              }
+            ]
           },
           {
             "type": "object",
@@ -235,6 +343,10 @@
                 "default": true,
                 "description": "The recorder clicks the field before typing, and that click is what opens the typing zoom on it. false types into the field as it is already focused: for a keystroke that finishes earlier typing (a submitting Enter) rather than starting it, where a second click rings a click effect on empty space beside the text."
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -259,14 +371,19 @@
                 "type": "string",
                 "enum": ["end", "start"],
                 "description": "where the caret goes after the focusing click, before the first character: a click lands it where the pointer hit, and a code editor line is typed at its end"
+              },
+              "guard": {
+                "type": "string",
+                "enum": ["spend"],
+                "description": "the step costs something real (credits, a purchase, a message sent): `vos record --dry-run` hovers it and never presses it, and `vos record` presses it only with `--confirm <id>`, refusing before any capture otherwise. Needs an id. A hosted take refuses a guarded step"
               }
             }
           },
           {
             "type": "object",
-            "required": ["do", "key"],
+            "required": ["do"],
             "additionalProperties": false,
-            "description": "One named key, recorded as a typing ping where the pointer is (or on selector when given, with no click): Escape closes what a click opened, Enter submits what was typed, Tab moves on, an arrow nudges. Never a character: words are typed with type.",
+            "description": "A key, a chord or a sequence, each recorded as a typing ping where the pointer is (or on selector when given, with no click), never as the key itself. key names one control key (Escape closes what a click opened, Enter submits what was typed); keys names a chord (\"Shift+D\", \"Mod+Z\", Mod being Meta on macOS and Control elsewhere), a plain key (\"r\", a tool's shortcut) or a sequence ([\"v\", \"Escape\"]), 150 ms apart. Words are typed with type.",
             "properties": {
               "do": {
                 "const": "press"
@@ -290,6 +407,24 @@
                   "Space"
                 ]
               },
+              "keys": {
+                "oneOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 50,
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                ],
+                "description": "a key name or chord (modifiers Shift, Control, Alt, Meta, Mod, ControlOrMeta joined with + before the key; a key is a single character, a named key like Escape or ArrowLeft, F1 to F24, or a code like KeyA or Digit1), or a list of them pressed in order"
+              },
               "selector": {
                 "type": "string",
                 "description": "the element the key is about: the ping and the step's rect are its, with no click"
@@ -299,6 +434,10 @@
                 "minimum": 0,
                 "description": "the read after the key, ms (default 150), held from the page's last visual change like a click's"
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -313,8 +452,21 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              },
+              "guard": {
+                "type": "string",
+                "enum": ["spend"],
+                "description": "the step costs something real (credits, a purchase, a message sent): `vos record --dry-run` hovers it and never presses it, and `vos record` presses it only with `--confirm <id>`, refusing before any capture otherwise. Needs an id. A hosted take refuses a guarded step"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["key"]
+              },
+              {
+                "required": ["keys"]
+              }
+            ]
           },
           {
             "type": "object",
@@ -332,6 +484,10 @@
               "dy": {
                 "type": "number"
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -365,6 +521,10 @@
                 "type": "number",
                 "minimum": 0
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -384,9 +544,9 @@
           },
           {
             "type": "object",
-            "required": ["do", "tx", "ty"],
+            "required": ["do"],
             "additionalProperties": false,
-            "description": "Press-move-release: drag an element, slide a range input, move a clip. Start = selector center when given, else (x, y); end = (tx, ty), eased over ms.",
+            "description": "Press-move-release: drag an element, slide a range input, move a clip. Start = selector center when given, else (x, y); end = (tx, ty), eased over ms. With path, the drag DRAWS: the press at the path's first point, a move at every later point in order (never dropped, so a page that answers slowly makes the stroke late, reported as meta.steps[].overrunMs, never a different stroke), the release at its last. modifiers are held from the press to the release.",
             "properties": {
               "do": {
                 "const": "drag"
@@ -410,10 +570,287 @@
                 "type": "number",
                 "minimum": 0
               },
+              "path": {
+                "oneOf": [
+                  {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 20000,
+                    "items": {
+                      "$ref": "#/$defs/pathPoint"
+                    }
+                  },
+                  {
+                    "type": "string",
+                    "pattern": "^(?!\\.)(?!.*\\.\\.)[^/\\\\]+$",
+                    "description": "a JSON file beside the actions file (a plain name) holding the points, or { \"points\": [...] }"
+                  }
+                ],
+                "description": "viewport points to draw through, replayed by their own times (tMs from the first point) or, untimed, evenly over ms. A point that carries pressure draws the whole path with a pen (pointer events with that pressure); without, the mouse draws it. A path takes no selector, x, y, tx or ty"
+              },
+              "modifiers": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "enum": ["Alt", "Shift", "Meta", "Control", "Mod"]
+                },
+                "description": "held from the press to the release (Alt-drag to duplicate, Shift to constrain); Mod is Meta on macOS, Control elsewhere"
+              },
               "ms": {
                 "type": "number",
                 "minimum": 0,
-                "default": 700
+                "default": 700,
+                "description": "the travel of a straight drag, or of an untimed path (default 700)"
+              },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            },
+            "oneOf": [
+              {
+                "required": ["tx", "ty"],
+                "not": {
+                  "required": ["path"]
+                }
+              },
+              {
+                "required": ["path"]
+              }
+            ]
+          },
+          {
+            "type": "object",
+            "required": ["do"],
+            "additionalProperties": false,
+            "description": "Check the page is as the flow expects, on camera, with no cursor move: exactly one of selector (visible; with enabled, enabled or disabled), text (some visible text contains it) or gone (no longer visible). A condition that never holds is a skip with its reason, which --strict turns into exit 2.",
+            "oneOf": [
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["gone"]
+              }
+            ],
+            "properties": {
+              "do": {
+                "const": "expect"
+              },
+              "selector": {
+                "type": "string",
+                "minLength": 1
+              },
+              "text": {
+                "type": "string",
+                "minLength": 1
+              },
+              "gone": {
+                "type": "string",
+                "minLength": 1
+              },
+              "enabled": {
+                "type": "boolean",
+                "description": "with selector: wait for the element to be enabled (true) or disabled (false)"
+              },
+              "timeout": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 5,
+                "description": "seconds to wait for the condition"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "until"],
+            "additionalProperties": false,
+            "description": "Wait OFF CAMERA for something slow (a render, a generated result): the capture stops, the condition is polled, and the capture resumes when it holds, so the footage has no gap and no frozen stretch. The cut lands in meta.skips[] ({ step, id, at, ms }) and becomes a segment boundary in the planned doc.json. A rehearsal waits for real and prints the time.",
+            "properties": {
+              "do": {
+                "const": "await"
+              },
+              "until": {
+                "type": "object",
+                "additionalProperties": false,
+                "minProperties": 1,
+                "maxProperties": 1,
+                "properties": {
+                  "selector": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "text": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "gone": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              },
+              "timeout": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 600,
+                "description": "the most seconds to wait"
+              },
+              "poll": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 2,
+                "description": "seconds between looks"
+              },
+              "reload": {
+                "type": "boolean",
+                "default": false,
+                "description": "reload the page between looks"
+              },
+              "onTimeout": {
+                "type": "string",
+                "enum": ["fail", "continue"],
+                "default": "fail",
+                "description": "fail: the take stops there, exit 1; continue: the capture resumes and the skip records timedOut"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do"],
+            "additionalProperties": false,
+            "description": "Keep a file the page makes, in the take's outputs/: selector clicks a control and waits up to 30 s for the browser's download; src fetches the currentSrc of a video, audio or img element with the page's own cookies. Listed in meta.outputs[] ({ step, id, name, bytes, contentType }). A download that never arrives is a skip with its reason. A hosted take refuses a download.",
+            "oneOf": [
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["src"]
+              }
+            ],
+            "properties": {
+              "do": {
+                "const": "download"
+              },
+              "selector": {
+                "type": "string",
+                "minLength": 1
+              },
+              "src": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector (the same grammar as every other step) of a video, audio or img element"
+              },
+              "as": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!\\.)(?!.*\\.\\.)[^/\\\\]+$",
+                "description": "the file name inside outputs/ (a plain name: no path separator, no \"..\"); absent, the name the page suggested"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do"],
+            "additionalProperties": false,
+            "description": "Put words or a file on the clipboard and paste it the way a person's ⌘V does: the browser's own clipboard and a trusted paste chord, so the page gets a trusted keydown and paste event and navigator.clipboard.read() sees the item; when the browser refuses the item, a paste event dispatched in the page (untrusted, said in the log). Into selector (clicked first) or where the focus is. Recorded as a typing ping, never its contents. A hosted take refuses a paste.",
+            "oneOf": [
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["file"]
+              }
+            ],
+            "properties": {
+              "do": {
+                "const": "paste"
+              },
+              "selector": {
+                "type": "string",
+                "minLength": 1,
+                "description": "the element to paste into, clicked first"
+              },
+              "text": {
+                "type": "string",
+                "description": "the words to paste"
+              },
+              "file": {
+                "type": "string",
+                "pattern": "^(?!\\.)(?!.*\\.\\.)[^/\\\\]+\\.(png|jpe?g|webp|gif|svg|txt|md|html?|json|csv)$",
+                "description": "a file beside the actions file, by a plain name, at most 10 MB: an image (a picture other than PNG is pasted as PNG), an SVG (also as its markup), or text"
+              },
+              "ms": {
+                "type": "number",
+                "minimum": 0,
+                "description": "the read after the paste, ms (default 150), held from the page's last visual change like a click's"
+              },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
               },
               "id": {
                 "type": "string",
@@ -435,5 +872,45 @@
         ]
       }
     }
+  },
+  "$defs": {
+    "pathPoint": {
+      "oneOf": [
+        {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 4,
+          "items": {
+            "type": "number"
+          },
+          "description": "[x, y], [x, y, tMs] or [x, y, tMs, pressure]: every point timed or none"
+        },
+        {
+          "type": "object",
+          "required": ["x", "y"],
+          "additionalProperties": false,
+          "properties": {
+            "x": {
+              "type": "number",
+              "minimum": 0
+            },
+            "y": {
+              "type": "number",
+              "minimum": 0
+            },
+            "t": {
+              "type": "number",
+              "minimum": 0,
+              "description": "ms"
+            },
+            "pressure": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          }
+        }
+      ]
+    }
   }
 }