@vosjs/cli 0.8.4 → 0.9.0

package/schema/actions.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vos.so/schemas/actions.schema.json",
+  "title": "vosso actions script",
+  "description": "Declarative browser flow executed by `vos record` \u2014 the recipe an agent writes after exploring a site. The recorder synthesizes the cursor track from these steps.",
+  "type": "object",
+  "required": ["steps"],
+  "additionalProperties": false,
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Page to record (overridable with --url)."
+    },
+    "viewport": {
+      "type": "object",
+      "required": ["width", "height"],
+      "additionalProperties": false,
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 320,
+          "default": 1280
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 240,
+          "default": 720
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["do", "ms"],
+            "additionalProperties": false,
+            "properties": {
+              "do": {
+                "const": "wait"
+              },
+              "ms": {
+                "type": "number",
+                "minimum": 0
+              },
+              "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."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "selector"],
+            "additionalProperties": false,
+            "properties": {
+              "do": {
+                "const": "hover"
+              },
+              "selector": {
+                "type": "string"
+              },
+              "ms": {
+                "type": "number",
+                "minimum": 0,
+                "default": 700,
+                "description": "Dwell \u2014 parked cursor becomes a zoom signal."
+              },
+              "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."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "selector"],
+            "additionalProperties": false,
+            "properties": {
+              "do": {
+                "const": "click"
+              },
+              "selector": {
+                "type": "string"
+              },
+              "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."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "selector", "text"],
+            "additionalProperties": false,
+            "description": "Typing is a zoom signal \u2014 a type step earns a held frame on its field (the click into it opens the span, the camera releases after the last character). ~0.6s+ of typing qualifies, so pace delayMs like a person (60-90ms) for a camera moment.",
+            "properties": {
+              "do": {
+                "const": "type"
+              },
+              "selector": {
+                "type": "string"
+              },
+              "text": {
+                "type": "string"
+              },
+              "delayMs": {
+                "type": "number",
+                "minimum": 0,
+                "default": 40
+              },
+              "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."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "dy"],
+            "additionalProperties": false,
+            "properties": {
+              "do": {
+                "const": "scroll"
+              },
+              "dy": {
+                "type": "number"
+              },
+              "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."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "x", "y"],
+            "additionalProperties": false,
+            "properties": {
+              "do": {
+                "const": "move"
+              },
+              "x": {
+                "type": "number",
+                "minimum": 0
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0
+              },
+              "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."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "tx", "ty"],
+            "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.",
+            "properties": {
+              "do": {
+                "const": "drag"
+              },
+              "selector": {
+                "type": "string"
+              },
+              "x": {
+                "type": "number",
+                "minimum": 0
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0
+              },
+              "tx": {
+                "type": "number",
+                "minimum": 0
+              },
+              "ty": {
+                "type": "number",
+                "minimum": 0
+              },
+              "ms": {
+                "type": "number",
+                "minimum": 0,
+                "default": 700
+              },
+              "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."
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/schema/channel-specs.json

@@ -0,0 +1,168 @@
+{
+  "$comment": "Per-channel launch-asset specs \u2014 the data the launch-kit skill loops over (mirrored as references/channel-specs.md in vosjs/skills; update together). Verified against official platform docs 2026-08-04; platform specs drift, re-verify quarterly. Image specs carry `genre`: 'screenshot' = real UI from the take (store policy demands real UX); 'card' = a composed cover \u2014 rendered from the poster program when one is in hand.",
+  "version": 1,
+  "verified": "2026-08-04",
+  "specs": [
+    {
+      "channel": "youtube",
+      "asset": "main-demo",
+      "kind": "video",
+      "w": 1920,
+      "h": 1080,
+      "minSeconds": 60,
+      "maxSeconds": 120,
+      "format": "mp4 (H.264+AAC)",
+      "notes": "Captions burned in. The same public upload serves the Chrome Web Store promo video and Product Hunt video (both take YouTube URLs only)."
+    },
+    {
+      "channel": "x",
+      "asset": "feed-cut",
+      "kind": "video",
+      "w": 1920,
+      "h": 1080,
+      "minSeconds": 30,
+      "maxSeconds": 140,
+      "maxBytes": 536870912,
+      "format": "mp4 (H.264+AAC ONLY \u2014 HEVC/VP9/AV1 rejected)",
+      "notes": "30\u201360s plays best; 140s/512MB is the free-tier ceiling. 1:1 also allowed. Native upload, never a link post."
+    },
+    {
+      "channel": "shorts-linkedin",
+      "asset": "vertical-cut",
+      "kind": "video",
+      "w": 1080,
+      "h": 1920,
+      "minSeconds": 30,
+      "maxSeconds": 90,
+      "format": "mp4 (H.264+AAC)",
+      "notes": "Critical text inside a centered ~900\u00d71160 safe zone \u2014 platform chrome covers the rest. Serves YouTube Shorts and LinkedIn native vertical."
+    },
+    {
+      "channel": "github",
+      "asset": "readme-loop",
+      "kind": "video",
+      "w": 1920,
+      "h": 1080,
+      "minSeconds": 10,
+      "maxSeconds": 20,
+      "maxBytes": 10485760,
+      "format": "mp4 (H.264)",
+      "notes": "\u226410MB is the free-plan attachment ceiling; two-pass target bitrate from duration."
+    },
+    {
+      "channel": "youtube",
+      "asset": "thumbnail",
+      "kind": "image",
+      "w": 1280,
+      "h": 720,
+      "maxBytes": 2097152,
+      "format": "png|jpg",
+      "notes": "",
+      "genre": "card"
+    },
+    {
+      "channel": "cws",
+      "asset": "screenshot",
+      "kind": "image",
+      "w": 1280,
+      "h": 800,
+      "count": "1-5",
+      "format": "png|jpg",
+      "notes": "Real UX only \u2014 misleading listing images are a removal-grade violation. Full bleed, square corners.",
+      "genre": "screenshot"
+    },
+    {
+      "channel": "cws",
+      "asset": "small-promo-tile",
+      "kind": "image",
+      "w": 440,
+      "h": 280,
+      "format": "png|jpg",
+      "notes": "Listings without one rank lower. No text; fill the region; subject centered.",
+      "genre": "card"
+    },
+    {
+      "channel": "cws",
+      "asset": "marquee",
+      "kind": "image",
+      "w": 1400,
+      "h": 560,
+      "format": "png|jpg",
+      "notes": "Carousel eligibility.",
+      "genre": "card"
+    },
+    {
+      "channel": "cws",
+      "asset": "icon",
+      "kind": "image",
+      "w": 128,
+      "h": 128,
+      "format": "png",
+      "notes": "96\u00d796 art + 16px transparent padding."
+    },
+    {
+      "channel": "producthunt",
+      "asset": "thumbnail",
+      "kind": "image",
+      "w": 240,
+      "h": 240,
+      "maxBytes": 3145728,
+      "format": "gif|png",
+      "notes": "GIF animates on hover only \u2014 the first frame must stand alone.",
+      "genre": "card"
+    },
+    {
+      "channel": "producthunt",
+      "asset": "gallery",
+      "kind": "image",
+      "w": 1270,
+      "h": 760,
+      "count": "4-8",
+      "format": "png|jpg|gif",
+      "notes": "First image is the hero.",
+      "genre": "screenshot"
+    },
+    {
+      "channel": "x",
+      "asset": "feed-image",
+      "kind": "image",
+      "w": 1200,
+      "h": 675,
+      "format": "png|jpg",
+      "notes": "",
+      "genre": "card"
+    },
+    {
+      "channel": "linkedin",
+      "asset": "feed-image",
+      "kind": "image",
+      "w": 1200,
+      "h": 627,
+      "format": "png|jpg",
+      "notes": "1080\u00d71350 vertical also performs in the mobile feed.",
+      "genre": "card"
+    },
+    {
+      "channel": "og",
+      "asset": "card",
+      "kind": "image",
+      "w": 1200,
+      "h": 630,
+      "maxBytes": 1048576,
+      "format": "png|jpg",
+      "notes": "Text in the center ~1080\u00d7600. Set twitter:card=summary_large_image explicitly \u2014 og:image alone gets the small card.",
+      "genre": "card"
+    },
+    {
+      "channel": "github",
+      "asset": "social-preview",
+      "kind": "image",
+      "w": 1280,
+      "h": 640,
+      "maxBytes": 1048576,
+      "format": "png|jpg",
+      "notes": "Key text \u226550px from every edge.",
+      "genre": "card"
+    }
+  ]
+}

package/schema/digest.schema.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://vos.so/schemas/digest.schema.json",
+  "title": "vosso take digest (digest.json — how an agent sees a recording)",
+  "description": "Written by `vos digest <take>` into <take>/digest/. One MOMENT per thing the cursor telemetry says mattered, each with a footage frame and a crop around the target, in the doc's own units: `source` extents are seconds of footage, `output` the same window through trims and speed (null when cut away), `focus`/`rect` are normalized [0..1] fractions of the video frame (the zoom cx/cy convention — copy them into a ZoomSpan). `activity` is the fraction of pixels that changed per SOURCE second. `plan` holds the planners' proposals; `proposed` names which cover each moment. Read digest.json, then sheet.png, then a crop only where you must decide.",
+  "type": "object",
+  "required": [
+    "digestVersion",
+    "take",
+    "units",
+    "moments",
+    "plan",
+    "doc",
+    "images"
+  ],
+  "properties": {
+    "digestVersion": { "type": "integer", "const": 1 },
+    "take": {
+      "type": "object",
+      "properties": {
+        "sourceDuration": {
+          "type": "number",
+          "description": "seconds of footage"
+        },
+        "outputDuration": {
+          "type": "number",
+          "description": "seconds of rendered video (trims + speed)"
+        },
+        "width": { "type": "number", "description": "cursor space (CSS px)" },
+        "height": { "type": "number" },
+        "captureWidth": { "type": ["number", "null"] },
+        "captureHeight": { "type": ["number", "null"] },
+        "frameWidth": {
+          "type": ["number", "null"],
+          "description": "decoded frame px (null with --no-frames)"
+        },
+        "frameHeight": { "type": ["number", "null"] },
+        "surface": { "type": "string", "enum": ["tab", "window", "monitor"] },
+        "producer": { "type": "string", "enum": ["extension", "cli"] },
+        "pageUrl": { "type": ["string", "null"] },
+        "pageTitle": { "type": ["string", "null"] },
+        "hasMic": { "type": "boolean" },
+        "hasSystemAudio": { "type": "boolean" },
+        "hasCursor": {
+          "type": "boolean",
+          "description": "false = browser-recorder take: moments are head/tail/scenes only"
+        },
+        "windowFocusedFrac": { "type": ["number", "null"] }
+      }
+    },
+    "units": {
+      "type": "object",
+      "description": "The unit sentences, repeated so a reader never has to guess."
+    },
+    "moments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "kind",
+          "source",
+          "output",
+          "at",
+          "outputAt",
+          "focus",
+          "rect",
+          "activity",
+          "proposed",
+          "said",
+          "full",
+          "crop"
+        ],
+        "properties": {
+          "id": { "type": "string", "pattern": "^m[0-9]{2,}$" },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "head",
+              "tail",
+              "click",
+              "typing",
+              "scroll",
+              "dwell",
+              "idle",
+              "scene"
+            ]
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "in": { "type": "number" },
+              "out": { "type": "number" }
+            },
+            "required": ["in", "out"]
+          },
+          "output": {
+            "type": ["object", "null"],
+            "properties": {
+              "in": { "type": "number" },
+              "out": { "type": "number" }
+            }
+          },
+          "at": {
+            "type": ["number", "null"],
+            "description": "SOURCE instant of the frame; null = no frame (idle)"
+          },
+          "outputAt": { "type": ["number", "null"] },
+          "focus": {
+            "type": ["object", "null"],
+            "properties": {
+              "cx": { "type": "number" },
+              "cy": { "type": "number" }
+            }
+          },
+          "rect": {
+            "type": ["object", "null"],
+            "properties": {
+              "x": { "type": "number" },
+              "y": { "type": "number" },
+              "w": { "type": "number" },
+              "h": { "type": "number" }
+            }
+          },
+          "clicks": { "type": "integer" },
+          "pings": {
+            "type": "integer",
+            "description": "typing-activity pings in the session (never key identity)"
+          },
+          "activity": {
+            "type": ["number", "null"],
+            "minimum": 0,
+            "maximum": 1
+          },
+          "proposed": {
+            "type": "object",
+            "properties": {
+              "zoom": { "type": "string" },
+              "speed": { "type": "string" },
+              "tilt": { "type": "string" }
+            }
+          },
+          "said": { "type": ["string", "null"] },
+          "full": {
+            "type": ["string", "null"],
+            "description": "the footage frame, relative to digest/"
+          },
+          "crop": {
+            "type": ["string", "null"],
+            "description": "a crop around rect/focus, relative to digest/"
+          },
+          "box": {
+            "type": ["object", "null"],
+            "description": "the crop's source box in FRAME px (not doc units)",
+            "properties": {
+              "x": { "type": "number" },
+              "y": { "type": "number" },
+              "w": { "type": "number" },
+              "h": { "type": "number" }
+            }
+          }
+        }
+      }
+    },
+    "activity": {
+      "type": ["array", "null"],
+      "items": { "type": "number" },
+      "description": "index = SOURCE second"
+    },
+    "plan": {
+      "type": "object",
+      "properties": {
+        "zoom": { "type": "array" },
+        "speed": { "type": "array" },
+        "tilt": { "type": "array" }
+      },
+      "description": "The three planners run fresh under the doc's own style (source:'auto' spans, ids as in doc.json)."
+    },
+    "doc": {
+      "type": "object",
+      "properties": {
+        "manual": {
+          "type": "object",
+          "description": "counts of human-decided spans — never re-plan these away"
+        },
+        "zoomStyle": { "type": ["string", "null"] },
+        "tiltStyle": { "type": ["string", "null"] }
+      }
+    },
+    "style": {
+      "type": ["object", "null"],
+      "description": "--style: the reference doc's style fields, reported"
+    },
+    "transcript": {
+      "type": ["array", "null"],
+      "items": {
+        "type": "object",
+        "properties": {
+          "start": { "type": "number" },
+          "end": { "type": "number" },
+          "text": { "type": "string" }
+        }
+      }
+    },
+    "images": {
+      "type": "object",
+      "properties": {
+        "full": { "type": "integer" },
+        "crop": { "type": "integer" },
+        "sheet": { "type": ["string", "null"] },
+        "tokensEstimateClaude": {
+          "type": "integer",
+          "description": "sum of (w×h)/750 over full + crop images — a budget hint, not a bill"
+        }
+      }
+    }
+  }
+}