@vosjs/cli 0.8.5 → 0.9.1

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { Browser } from 'playwright';
+import { Browser, Page } from 'playwright';
+import { CursorTrack, RecordingMeta, ProjectDoc, CursorEvent, TranscriptSegment, Digest } from '@vosjs/studio-core';
+export { Digest } from '@vosjs/studio-core';
 
 interface RenderCommonOptions {
     config: Record<string, unknown>;
@@ -60,4 +62,477 @@ declare class BrowserUnavailableError extends Error {
  */
 declare function launchBrowser(): Promise<Browser>;
 
-export { BrowserUnavailableError, type LoadedConfig, type RenderResult, type RenderStillOptions, type RenderVideoOptions, configDuration, launchBrowser, loadVosConfig, previewPages, renderStill, renderVideo };
+/** Entry point — the delegation contract for @vosjs/cli: the host forwards
+    every non-engine verb here (`vos <verb>`; `vos voila <verb>` stays a
+    hidden alias until public launch). The exported `manifest` (index.ts)
+    tells the host which verbs exist and how to summarize them in help. */
+declare function run(argv: string[]): Promise<number>;
+
+/**
+ * The verb manifest of the take pipeline and the vos.so verbs — what
+ * `vos help` lists under the engine verbs. It kept the shape a separately
+ * installed plugin once handed the host (name + host range), so a script
+ * reading it keeps working.
+ */
+interface PluginVerb {
+    name: string;
+    summary: string;
+}
+interface PluginManifest {
+    name: string;
+    /** Host versions this plugin speaks the run(argv) contract with. */
+    hostRange: string;
+    verbs: PluginVerb[];
+}
+declare const manifest: PluginManifest;
+
+/**
+ * The action script — the declarative recipe an agent (or human) writes to
+ * drive a take. Small on purpose: selectors + a handful of verbs. The recorder
+ * executes it with humanized cursor motion and synthesizes the CursorTrack
+ * from its own dispatches.
+ */
+interface ActionsFile {
+    /** Page to record. `--url` overrides. */
+    url?: string;
+    /** Recording viewport in CSS px (default 1280x720). */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    steps: ActionStep[];
+}
+type ActionStep = ({
+    do: 'wait';
+    ms: number;
+} | {
+    do: 'hover';
+    selector: string;
+    ms?: number;
+} | {
+    do: 'click';
+    selector: string;
+} | {
+    do: 'type';
+    selector: string;
+    text: string;
+    delayMs?: number;
+} | {
+    do: 'scroll';
+    dy: number;
+} | {
+    do: 'move';
+    x: number;
+    y: number;
+}
+/**
+ * Press-move-release — real edits (drag an element on the stage canvas,
+ * slide a range input, move a timeline clip). Start = the selector's center
+ * when given, else (x, y); end = (tx, ty); eased over ms (default 700).
+ */
+ | {
+    do: 'drag';
+    selector?: string;
+    x?: number;
+    y?: number;
+    tx: number;
+    ty: number;
+    ms?: number;
+}) & {
+    /**
+     * Optional stable identity: anchors in doc.json name a step by this
+     * id (else by index), so a step can move or gain neighbours across script
+     * edits without breaking the cut anchored to it. Unique when present.
+     */
+    id?: string;
+};
+/** Structural validation with actionable messages. Returns [] when valid. */
+declare function validateActions(value: unknown): string[];
+
+declare const RECORDING_NAME = "recording.webm";
+interface TakePaths {
+    dir: string;
+    recording: string;
+    framesDir: string;
+    framesIndex: string;
+    cursor: string;
+    meta: string;
+    actions: string;
+    doc: string;
+}
+declare function takePaths(dir: string): TakePaths;
+interface TakeData {
+    paths: TakePaths;
+    cursor: CursorTrack;
+    meta: RecordingMeta;
+    actions: ActionsFile | null;
+    doc: ProjectDoc | null;
+}
+/** Load a take directory; cursor+meta are required, doc/actions optional. */
+declare function loadTake(dir: string): Promise<TakeData>;
+
+interface FrameRec {
+    file: string;
+    /** ms since t0 */
+    tMs: number;
+}
+interface SkippedStep {
+    /** index into actions.steps */
+    step: number;
+    do: string;
+    selector: string;
+}
+/** A stretch with no screencast frames — the page pixels did not change. */
+interface FreezeSpan {
+    /** seconds into the take */
+    from: number;
+    to: number;
+    ms: number;
+}
+interface RecordResult {
+    events: CursorEvent[];
+    frames: FrameRec[];
+    meta: RecordingMeta;
+    /** steps whose selector never became visible — the take continued without them. */
+    skipped: SkippedStep[];
+    /** the initial goto never reached networkidle (recording proceeded anyway). */
+    navTimeout: boolean;
+    /**
+     * Smoothness telemetry: stretches ≥400ms with no visual change. Frozen
+     * footage is the #1 enemy of a smooth product video — either the flow should
+     * keep motion in frame (animate, hover a preview, scroll) or the doc should
+     * trim/speed through these. freezePct = share of the take that is frozen.
+     */
+    freezes: FreezeSpan[];
+    freezePct: number;
+    /** The take reached --max-duration and stopped there; later steps did not run. */
+    capped: boolean;
+}
+interface RecordOpts {
+    /** Stop the capture at this many seconds (the hosted cap). */
+    maxDurationSeconds?: number;
+}
+declare function recordTake(browser: Browser, url: string, actions: ActionsFile, paths: TakePaths, log: (msg: string) => void, opts?: RecordOpts): Promise<RecordResult>;
+
+declare function encodeRecording(browser: Browser, takeDir: string, onProgress: (fraction: number) => void): Promise<{
+    bytes: number;
+}>;
+
+/**
+ * Reuse: re-time a previous cut onto a NEW recording of the same
+ * script. The recorder's `meta.steps` say when each actions.json step ran
+ * in BOTH takes, so the old timeline maps onto the new one piecewise —
+ * matched step edges are the control points, and any source time in
+ * between interpolates. Explicit `anchor`s on camera spans resolve
+ * directly against the new steps and win over the map.
+ *
+ * Report, never guess: every span that
+ * could not re-anchor cleanly is NAMED in `flagged` with the reason in
+ * words — a vanished step, a skipped selector, a span clamped or dropped
+ * at the new take's edge. The agent fixes actions.json and re-runs; the
+ * verb never silently invents a cut.
+ *
+ * Pure functions, no I/O — reuse.test.ts drives them with synthetic
+ * step timelines; the browser gate is smoke-recut.ts.
+ */
+
+interface ReuseReport {
+    /** spans re-timed through an explicit anchor. */
+    anchored: number;
+    /** spans re-timed through the step map (approximate by nature). */
+    mapped: number;
+    /** everything that needs a human/agent look, in words. */
+    flagged: string[];
+}
+
+interface PlanSummary {
+    doc: ProjectDoc;
+    zoomAuto: number;
+    zoomManual: number;
+    cursorKept: boolean;
+    fresh: boolean;
+    /** The style fields copied from `--style`'s reference, when given. */
+    styleFrom?: string;
+    styleFields?: readonly string[];
+    /** `--reuse`: what the re-anchor did and what it could not. */
+    reuse?: ReuseReport & {
+        from: string;
+    };
+}
+interface PlanOptions {
+    /**
+     * Style transfer at the data layer: a signed-off take whose
+     * zoomStyle/zoomParams/speedParams/tiltStyle/frame/cursor/cam/export are
+     * copied onto this take BEFORE the planners run, so the auto spans are
+     * proposed under the series' camera. The cut (spans, overlays, audio) is
+     * never touched; a field absent on the reference is removed here too.
+     */
+    style?: {
+        from: string;
+        doc: ProjectDoc;
+    };
+    /**
+     * The re-render loop: a PREVIOUS cut of the same script (a
+     * re-record's doc.prev.json) applied to this take's NEW footage. Style
+     * fields copy over like --style; the human's camera spans and trims
+     * re-time through the step map / explicit anchors; output-anchored work
+     * (overlays, audio, objects) carries at its output times; auto spans
+     * re-plan on the new cursor. The report NAMES whatever could not follow.
+     */
+    reuse?: {
+        from: string;
+        doc: ProjectDoc;
+    };
+}
+declare function planTake(dir: string, opts?: PlanOptions): Promise<PlanSummary>;
+
+interface DigestOptions {
+    outDir?: string;
+    full?: number;
+    crop?: number;
+    /** Skip the browser passes (moments only; activity null). */
+    frames?: boolean;
+    transcript?: readonly TranscriptSegment[] | null;
+    /** A reference doc whose style fields are REPORTED (never applied here). */
+    style?: {
+        from: string;
+        doc: ProjectDoc;
+    } | null;
+}
+
+interface DigestResult {
+    file: string;
+    outDir: string;
+    digest: Digest;
+    bytes: number;
+}
+declare function digestTake(browser: Browser | null, dir: string, opts?: DigestOptions): Promise<DigestResult>;
+/** Accept Whisper's `{segments:[…]}` or a bare `[{start,end,text}]`. */
+declare function parseTranscript(raw: unknown): TranscriptSegment[];
+
+interface MediaPullResult {
+    downloaded: {
+        file: string;
+        assetId: string;
+        bytes: number;
+    }[];
+    kept: string[];
+}
+declare function pullMedia(ctx: {
+    origin: string;
+    key: string | null;
+}, dir: string, doc: ProjectDoc, log: (line: string) => void): Promise<MediaPullResult>;
+
+interface DocOverrides {
+    /** raw `path=value` expressions from repeated --set. */
+    set?: string[];
+    /** --frame alias → frame.browserBar.kind. */
+    frame?: string;
+    /** --background alias → frame.backgroundMedia (kind inferred from the URL,
+     *  or a backdrop SLUG from GET /api/backdrops, resolved by
+     *  resolveBackdropSlug before the sync apply). */
+    background?: string;
+    /** The loop length a resolved backdrop slug brought with it. */
+    backgroundDuration?: number;
+    /** Platform origin for slug resolution (platformOrigin(flags)). */
+    origin?: string;
+}
+
+interface RenderTakeOptions {
+    width?: number;
+    height?: number;
+    fps?: number;
+    format?: 'webm' | 'mp4';
+    /** Concurrent chunk renders (timeline sharding); 1 = single-flight. */
+    parallel?: number;
+    /** OUTPUT-time subrange [start, end) seconds — spot-check a doc edit cheaply. */
+    range?: [number, number];
+    /** Draft mode: half resolution + low bitrate, for iteration only. */
+    draft?: boolean;
+    /** Encoder bitrate override (a destination's byte ceiling as a budget). */
+    bitrate?: number;
+    /** In-memory doc overrides (--set / --frame / --background); lint-gated. */
+    overrides?: DocOverrides;
+    onPhase?: (phase: string) => void;
+    onProgress?: (fraction: number) => void;
+}
+interface RenderTakeResult {
+    out: string;
+    bytes: number;
+    width: number;
+    height: number;
+    fps: number;
+    duration: number;
+    zoomSpans: number;
+    clicks: number;
+    /** Number of chunks rendered (1 unless --parallel raised it). */
+    chunks: number;
+    /** An audio track was mixed + muxed (doc.audio clips / mic). */
+    audio: boolean;
+}
+declare function renderTake(browser: Browser, dir: string, outFile: string, opts: RenderTakeOptions): Promise<RenderTakeResult>;
+
+interface RenderAnimationOptions {
+    /** Compiled vos animation code (module exporting initVos). */
+    animationCode: string;
+    /** Directory the page server roots at; chunk artifacts land here too. */
+    workDir: string;
+    /** Source video file name inside workDir (studio takes), served → blob URL. */
+    videoFile?: string;
+    /** Token inside animationCode replaced with the video blob URL. */
+    videoToken?: string;
+    width: number;
+    height: number;
+    fps: number;
+    duration: number;
+    format: 'webm' | 'mp4';
+    /** Max simultaneous chunk pages; 1 = single-flight (no concat). */
+    parallel?: number;
+    /**
+     * First GLOBAL frame to render (a range render: seek time starts here while
+     * output timestamps stay zero-based). duration then covers the range only.
+     */
+    frameOffset?: number;
+    /** Encoder bitrate override (draft renders); default 10 Mbps. */
+    bitrate?: number;
+    /**
+     * Mix + mux an audio track in the SAME render (single-flight only — audio
+     * stays out of chunks by design, mirroring the cloud single-flight path).
+     * `producerCode` defines window.__vosAudioProducer__ (render-core);
+     * `data` is the lowered composition data (videoToken replaced in-page).
+     * `duration` is the FULL timeline — the producer builds the whole mix and
+     * the page slices its own frame window, so a range render keeps audio.
+     */
+    audio?: {
+        producerCode: string;
+        data: unknown;
+        duration: number;
+    };
+    onProgress?: (fraction: number) => void;
+}
+interface RenderAnimationResult {
+    bytes: Uint8Array;
+    totalFrames: number;
+    /** Number of chunks actually rendered (1 = single-flight). */
+    chunks: number;
+}
+declare function renderAnimation(browser: Browser, opts: RenderAnimationOptions): Promise<RenderAnimationResult>;
+
+/** One agent-browser command with its result: the `batch` record shape. */
+interface AgentBrowserRecord {
+    command: string[] | string;
+    /** Single-command `--json` lines carry `data`; batch records carry `result`. */
+    data?: unknown;
+    result?: unknown;
+    success?: boolean;
+    error?: string | null;
+}
+interface ConvertOptions {
+    /** Overrides the walk's first `open`. */
+    url?: string;
+    /** Overrides the walk's `set viewport`. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+interface ConvertResult {
+    actions: ActionsFile;
+    /** Every command that became no step, or a different step, with its line. */
+    notes: string[];
+    /** Commands that produced a step. */
+    steps: number;
+    /** Reads and session verbs: nothing to replay. */
+    ignored: number;
+    /** Actions the recorder cannot follow, or that failed in the walk. */
+    skipped: number;
+}
+/** Parse a steps.jsonl (or a batch array) into records; malformed lines are named. */
+declare function parseAgentBrowserLog(text: string): {
+    records: AgentBrowserRecord[];
+    problems: string[];
+};
+/** Shell-style split for a `command` kept as one string: quotes group, backslash escapes. */
+declare function splitCommand(command: string): string[];
+/** The walk, as steps the recorder can replay. Pure. */
+declare function convertAgentBrowser(records: AgentBrowserRecord[], opts?: ConvertOptions): ConvertResult;
+
+interface TakeServer {
+    base: string;
+    close: () => void;
+}
+/**
+ * Static server over the take dir + generated pages + a POST /save endpoint
+ * the in-page encoder/renderer uses to hand bytes back to node. The recording
+ * is fetched → blob URL (seekable), but a take-dir VIDEO BACKGROUND
+ * (frame.backgroundMedia.key = "/bg.webm") is loaded directly by ON_FRAME and
+ * seeked during export — so this serves Range/206 (an HTMLVideoElement hangs
+ * forever seeking a naive 200-only static server).
+ */
+declare function startTakeServer(rootDir: string, pages: Record<string, string>): Promise<TakeServer>;
+/** Poll a capture/encode page for window.__done / __error / __progress. */
+declare function waitForPageDone(page: Page, label: string, onProgress: (fraction: number) => void, timeoutMs: number): Promise<Record<string, unknown>>;
+
+/**
+ * Origin resolution: --origin (or legacy --api) → VOS_ORIGIN → legacy
+ * VOS_API_BASE (which historically carried a trailing /api) → https://vos.so.
+ * Every shape converges on a bare origin; paths below carry the /api prefix.
+ */
+declare function platformOrigin(flags?: {
+    origin?: string;
+    api?: string;
+}): string;
+/**
+ * Accepts a bare vos id, a watch URL (vos.so/vos/{id}), an embed URL
+ * (/embed/vos/{id}), or a studio/stage URL (?vos={id}).
+ */
+declare function parseVosId(input: string): string;
+/**
+ * The full documented ladder: explicit --key → VOS_API_KEY → the first line
+ * of ~/.config/vos/credentials. A vos_rg_ remix grant is just a key here.
+ * Returns null when nothing resolves — callers decide whether auth is needed.
+ */
+declare function resolveCredential(explicit?: string): string | null;
+interface ApiResult {
+    status: number;
+    body: Record<string, unknown>;
+}
+declare function apiJson(origin: string, path: string, init?: {
+    method?: string;
+    key?: string | null;
+    body?: unknown;
+    /** Raw request body (uploads) — used verbatim, with `headers`. */
+    raw?: Uint8Array;
+    headers?: Record<string, string>;
+}): Promise<ApiResult>;
+/** Human-readable error line for a failed platform response. Never echoes credentials. */
+declare function apiError(what: string, r: ApiResult): string;
+interface SyncState {
+    vosId: string;
+    /** The hosted version this directory is based on — the next push's base. */
+    versionId: string | null;
+    pushedAt?: string;
+    title?: string;
+    slug?: string;
+    remixOfId?: string;
+}
+/**
+ * vos.json → legacy push.json ({vosId, versionId}) → legacy meta.json
+ * ({id, currentVersionId} — guarded on a string `id` so a take dir's
+ * RecordingMeta meta.json is never misread as sync state).
+ */
+declare function readSyncState(dir: string): SyncState | null;
+/** Merge-writes vos.json; the legacy files are left alone (read-only compat). */
+declare function writeSyncState(dir: string, patch: Partial<SyncState> & {
+    vosId: string;
+}): SyncState;
+interface VersionChange {
+    versionId?: string;
+    versionNumber?: number;
+    origin?: string;
+    label?: string | null;
+    note?: string | null;
+    summary?: string;
+}
+
+export { type ActionStep, type ActionsFile, type AgentBrowserRecord, BrowserUnavailableError, type ConvertOptions, type ConvertResult, type DigestOptions, type DigestResult, type LoadedConfig, RECORDING_NAME, type RenderAnimationOptions, type RenderAnimationResult, type RenderResult, type RenderStillOptions, type RenderTakeOptions, type RenderTakeResult, type RenderVideoOptions, type SyncState, type TakeData, type TakePaths, type TakeServer, type VersionChange, apiError, apiJson, configDuration, convertAgentBrowser, digestTake, encodeRecording, launchBrowser, loadTake, loadVosConfig, manifest, parseAgentBrowserLog, parseTranscript, parseVosId, planTake, platformOrigin, previewPages, pullMedia, readSyncState, recordTake, renderAnimation, renderStill, renderTake, renderVideo, resolveCredential, run, splitCommand, startTakeServer, takePaths, validateActions, waitForPageDone, writeSyncState };

package/dist/index.js

@@ -1,20 +1,78 @@
 #!/usr/bin/env node
 import {
-  BrowserUnavailableError,
   configDuration,
-  launchBrowser,
   loadVosConfig,
   previewPages,
   renderStill,
   renderVideo
-} from "./chunk-3VPLPEMZ.js";
+} from "./chunk-X2BKHZ56.js";
+import {
+  RECORDING_NAME,
+  apiError,
+  apiJson,
+  convertAgentBrowser,
+  digestTake,
+  encodeRecording,
+  loadTake,
+  parseAgentBrowserLog,
+  parseTranscript,
+  parseVosId,
+  planTake,
+  platformOrigin,
+  pullMedia,
+  readSyncState,
+  recordTake,
+  renderAnimation,
+  renderTake,
+  resolveCredential,
+  run,
+  splitCommand,
+  startTakeServer,
+  takePaths,
+  validateActions,
+  waitForPageDone,
+  writeSyncState
+} from "./chunk-74MSNLT2.js";
+import {
+  BrowserUnavailableError,
+  launchBrowser
+} from "./chunk-A2VSDK3C.js";
+import {
+  manifest
+} from "./chunk-5BFGODBI.js";
 export {
   BrowserUnavailableError,
+  RECORDING_NAME,
+  apiError,
+  apiJson,
   configDuration,
+  convertAgentBrowser,
+  digestTake,
+  encodeRecording,
   launchBrowser,
+  loadTake,
   loadVosConfig,
+  manifest,
+  parseAgentBrowserLog,
+  parseTranscript,
+  parseVosId,
+  planTake,
+  platformOrigin,
   previewPages,
+  pullMedia,
+  readSyncState,
+  recordTake,
+  renderAnimation,
   renderStill,
-  renderVideo
+  renderTake,
+  renderVideo,
+  resolveCredential,
+  run,
+  splitCommand,
+  startTakeServer,
+  takePaths,
+  validateActions,
+  waitForPageDone,
+  writeSyncState
 };
 //# sourceMappingURL=index.js.map

package/dist/manifest-3LIL5M3F.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import {
+  manifest
+} from "./chunk-5BFGODBI.js";
+export {
+  manifest
+};
+//# sourceMappingURL=manifest-3LIL5M3F.js.map

package/dist/manifest-3LIL5M3F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/run-I2XSZAWI.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  run
+} from "./chunk-74MSNLT2.js";
+import "./chunk-A2VSDK3C.js";
+export {
+  run
+};
+//# sourceMappingURL=run-I2XSZAWI.js.map

package/dist/run-I2XSZAWI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.8.5",
-  "description": "Command line for the vos programmatic video engine — render deterministic videos and stills from vos configs, headlessly, from your terminal or an AI agent.",
+  "version": "0.9.1",
+  "description": "The vos CLI: record the real product from a scripted browser flow, auto-zoom from the cursor track, cut as data in doc.json, render deterministic video and stills, deliver a release's media per destination spec, and sync with vos.so. One binary, every verb, MIT.",
   "type": "module",
   "license": "MIT",
   "author": "vosso",
-  "homepage": "https://vos.so/engine",
+  "homepage": "https://vos.so/cli",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vosjs/vos.git",
@@ -23,7 +23,11 @@
     "headless",
     "agent",
     "animation",
-    "three"
+    "three",
+    "screen-recording",
+    "product-video",
+    "demo",
+    "auto-zoom"
   ],
   "bin": {
     "vos": "./dist/cli.js"
@@ -37,13 +41,20 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "schema"
   ],
   "sideEffects": false,
   "dependencies": {
+    "mediabunny": "^1.27.3",
     "playwright": "^1.49.0",
     "@vosjs/core": "^0.23.1",
+    "@vosjs/editor": "^1.3.0",
+    "@vosjs/render-core": "^0.1.0",
+    "@vosjs/shared": "^0.1.0",
     "@vosjs/elements": "^0.8.0",
+    "@vosjs/studio-core": "^0.1.0",
+    "@vosjs/timeline": "^0.4.0",
     "@vosjs/tween": "^0.8.1"
   },
   "devDependencies": {