@vosjs/cli 0.83.2 → 0.84.0

package/README.md

@@ -192,6 +192,12 @@ vos look https://app.acme.com/projects --session acme --click '[data-testid="new
 
 It writes `<out>/look.png` (the viewport; `--out look` by default) and lists every control in view (buttons, links, tabs, menu items, checkboxes, switches, options, fields, editable regions, and anything with a test id) with its tag, role, accessible name, test id, link path and query, rect in viewport px, whether it is disabled, inside an open dialog or covered by something on top of it, and ONE proposed selector: its test id; else its `aria-label`, inside the open dialog it sits in; else a link's own `href`, query kept (two tiles to `?vos=a` and `?vos=b` are two links); else role and name (`role=button[name="Continue"]`, what `page.locator` reads), narrowed by its dialog or landmark when that is what makes it one; else a field's own `name` or `placeholder`, a written id, or its words inside its dialog or landmark. Never a position in the tree. Each proposal is counted with the recorder's own selector engine and marked `UNIQUE` (it reaches this element and no other) or `AMBIGUOUS` (it reaches others too, and the recorder would take the first). A control whose words hold an address, a key or a card number is listed with those words withheld, and the frame's exposures are said the way a rehearsal says them. Looking never spends or destroys: a `--click` whose target's words begin with a stem that does (delet, remov, revok, eras, discard, publish, deploy, purchas, subscri, unsubscri, pay, buy, generat, submit, send, transfer, upgrad, confirm, leav, destroy, so `Allow deleting` and `Revoke` are caught with `Delete`), or say move to trash, empty trash or cancel subscription, is refused in words before it is pressed (exit 2), and `--type` fills a field without pressing Enter. A look cannot know every spend: `Make a video` or `Create` on a primary button may start paid work and passes, because refusing every Make would refuse half of every app. The list is a floor under looking; in a recorded flow, a step's `guard: "spend"` in `actions.json` is the fence. A sign-in in front of the page is the wall check's verdict, exit 4; the sign-in page is still looked at, since it is what a `setup` step scripts past. `--wait <ms>` adds a pause before the look for a page that animates in; `--json` prints the whole look as one done event (`url`, `screenshot`, `controls`, `exposures`, `wall`).
 
+**Past a step that creates: `vos look --actions actions.json --until <step id>`.** The state a flow is about often exists only after a click that makes something (the dialog that shows a new key appears after Create), and `--click` takes one hand-written step. `--until` walks the script's own steps the way a rehearsal does, on the same door (its `setup`, its `mask`, `--session` or `--storage-state`, a `guard: "spend"` step hovered and never pressed), stops after the step whose `id` it names, and looks at the page as that step left it; the steps after it never run. The URL and viewport are the script's unless given. The walk clicks for real, so the script's `teardown` runs after the look and its line ends the report. A step skipped on the way is named and exits 2 (the page may not be the one the script reaches), a step that is never reached says why, and an `--until` that names no step lists the ids the script has. It never takes `--click` or `--type` beside it.
+
+```bash
+vos look --actions actions.json --until create --session acme   # the page after the step with "id": "create"
+```
+
 **`setup`: the steps that run before the camera rolls.** A sign-in form, a cookie banner, the "choose your editor" modal, an onboarding tour: things a take must get past and must not show. `actions.json` takes `setup: [...]` beside `steps`, with the verbs `goto`, `click`, `type`, `press`, `wait`, and the guard `if`. They run after the first navigation and before a frame is captured, as plain actions with no cursor, no frames, no pace and nothing in `meta.steps`; then the recorder opens `url` again and the take begins where the setup left it. A `type` step's `text` may be `{ "env": "DEMO_PASSWORD" }`, read from the shell at run time and never logged or stored (the log names the field, never the value; a literal typed into a password field is refused by `validate`, because `actions.json` is committed and pushed with the take). A selector that never appears fails the take before anything is recorded (exit 2), because a take that begins at a half-finished sign-in is the wall by another name; rehearse the setup with `--dry-run` like everything else. This is rung 2 of the session ladder made scriptable: a local or self-hosted instance with a seeded user, no state file needed.
 
 ```json
@@ -544,7 +550,7 @@ vos assets ls [--kind <kind>] [--q <text>] [--sort size] | usage | why <id>   #
 vos recipe push <FILE.md> --folder <slug> | --asset <id>   # the one recipe write: create, or replace in place
 ```
 
-`push` is polymorphic by a deterministic sniff, never a flag: a take directory (a `doc.json` carrying `source`) pushes recording and document through the take pipeline; a `config.json` (or a directory holding one) pushes the program, and a `doc.json` beside it that carries `program` (a program document: overlays, objects, audio, speed, tween edits, its own length; `program.config` omitted on disk) rides along, lint-gated. `fetch` and `pull` write a program document back the same way. `pull` takes `--since <versionId>` (walk the changelog from that base instead of the tracked one) and `--check` (print what changed and stop: nothing on disk moves) on both paths. A program push LANDS where `vos.json` says: a directory that tracks a vos iterates it, so the fetch, edit, check, push, pull loop needs no flags, and making something separate from the same config is the explicit `--remix-of` door. Program pushes take `--vos`, `--title`, `--slug`, `--desc`, `--tags`, `--folder`, `--remix-of`, `--base`, `--label`, `--note`, `--override <id>` (repeatable) and `--claimable`; take pushes take `--title`, `--label`, `--note`, `--folder`, `--override`, `--yes`, `--bake` and `--claimable`. Both take `--wait`. A take push first asks the platform which `@vosjs/studio-core` it renders with (`GET /api/engine`, public, `{ studioCore, core }`) and refuses (exit 2), before anything uploads, a take that uses a field newer than it: the program a push compiles plays right, but the platform's studio lowers the stored document again with its own release, so it would show an anchored caption at its fallback start or play a clip with a loudness target at its gain, and every version saved from the studio would keep it that way. `--bake` sends a copy any renderer plays: every such field the take uses, said in what an older release reads (an anchored caption at the start it plays at in this cut with its `{elapsed}` filled, a loudness target as its gain, up to 1), whatever the platform answered, behind, current or nothing at all, and it never touches `doc.json`. The table of fields and their releases is `DOC_FEATURES` in `@vosjs/studio-core`. A platform that cannot say (no such endpoint, a refusal, no answer in 2 s) is warned of and pushed to. A new vos pushed without `--folder` lands unfiled, at the root of the shelf, and the done line says so. `--folder` takes a project on your own shelf (its slug or id) or anyone's project by its address, `<handle>/<slug>` as its page on vos.so names it: the server answers where the push lands, CONTINUING that project when the key is its owner's and otherwise STARTING the person's own from it (a private project made once, named after it, with the recipes they may read copied in, never its videos). The push says which.
+`push` is polymorphic by a deterministic sniff, never a flag: a take directory (a `doc.json` carrying `source`) pushes recording and document through the take pipeline; a `config.json` (or a directory holding one) pushes the program, and a `doc.json` beside it that carries `program` (a program document: overlays, objects, audio, speed, tween edits, its own length; `program.config` omitted on disk) rides along, lint-gated. `fetch` and `pull` write a program document back the same way. `pull` takes `--since <versionId>` (walk the changelog from that base instead of the tracked one) and `--check` (print what changed and stop: nothing on disk moves) on both paths. A program push LANDS where `vos.json` says: a directory that tracks a vos iterates it, so the fetch, edit, check, push, pull loop needs no flags, and making something separate from the same config is the explicit `--remix-of` door. Program pushes take `--vos`, `--title`, `--slug`, `--desc`, `--tags`, `--folder`, `--remix-of`, `--base`, `--label`, `--note`, `--override <id>` (repeatable) and `--claimable`; take pushes take `--title`, `--desc`, `--prompt`, `--label`, `--note`, `--folder`, `--override`, `--yes`, `--bake` and `--claimable`. Both take `--wait`. `--desc` (up to 500 characters, checked before anything uploads) and `--prompt` are the watch page's words, kept on the vos and never on a version: a first push creates the vos with them, a later push that names them replaces them, one that names neither leaves them as they are, on a program and a take alike. A take push first asks the platform which `@vosjs/studio-core` it renders with (`GET /api/engine`, public, `{ studioCore, core }`) and refuses (exit 2), before anything uploads, a take that uses a field newer than it: the program a push compiles plays right, but the platform's studio lowers the stored document again with its own release, so it would show an anchored caption at its fallback start or play a clip with a loudness target at its gain, and every version saved from the studio would keep it that way. `--bake` sends a copy any renderer plays: every such field the take uses, said in what an older release reads (an anchored caption at the start it plays at in this cut with its `{elapsed}` filled, a loudness target as its gain, up to 1), whatever the platform answered, behind, current or nothing at all, and it never touches `doc.json`. The table of fields and their releases is `DOC_FEATURES` in `@vosjs/studio-core`. A platform that cannot say (no such endpoint, a refusal, no answer in 2 s) is warned of and pushed to. A new vos pushed without `--folder` lands unfiled, at the root of the shelf, and the done line says so. `--folder` takes a project on your own shelf (its slug or id) or anyone's project by its address, `<handle>/<slug>` as its page on vos.so names it: the server answers where the push lands, CONTINUING that project when the key is its owner's and otherwise STARTING the person's own from it (a private project made once, named after it, with the recipes they may read copied in, never its videos). The push says which.
 
 **A program's files are declared, never typed into a function.** `config.json` names each file it uses in `assets` (`"assets": { "logo": { "ref": "./logo.png", "kind": "image" }, "shots": { "ref": ["./shots/1.png", "./shots/2.png"] } }`) and reads `ctx.assets.logo`, or `"$assets.logo"` in an element, object or font. On disk a `ref` is a path in the config's own directory or below, so `vos render`, `vos still` and `vos preview` serve the file to the page from disk. A path that climbs out of that directory (`../`, an absolute path, a link that points away) is not served and not uploaded, and a config loaded from a URL reads no local file: a program's code runs in a page, and what the page is served the program can send anywhere. `vos push` uploads each local file (content-addressed, so a re-push sends nothing: pictures, SVG, video, sound, `.glb` models, fonts and HDR environments) and what it stores names the hosted file as `asset:<id>`, the one spelling the platform resolves for every render; the config on disk keeps its paths. A file an element names as `src` or a font names as `url` is lifted into the manifest on the way (the element then names `"$assets.<name>"`), and a path in `data` that is a file beside the config is uploaded and rewritten to the hosted file's path, so every place a program can name a file crosses. A file typed inside a function cannot be rewritten: `vos push` says so, with the manifest line to write. `vos fetch --media` brings a program's hosted files home under `assets/` and re-points the manifest at them (`assets/.hosted.json` remembers which hosted file each one is, so a later fetch replaces one that changed); without `--media` the manifest keeps `asset:<id>` and a local render reads each file with your key. `vos check` says when a `"$assets.<name>"` names nothing, when a declared path is not a file, and when a function names a hosted file in code instead of the manifest: a file named only in code does not load on a render of a private program and does not follow a remix. A `--claimable` push carries them too, through the claim's own upload session (below).
 

package/dist/{chunk-HDJFCTOG.js → chunk-DM7ADA77.js}

@@ -148,9 +148,9 @@ function landedLines(l) {
 }
 
 // src/plugin/run.ts
-import { mkdir as mkdir13, readFile as readFile18, rm as rm6 } from "fs/promises";
+import { mkdir as mkdir13, readFile as readFile19, rm as rm7 } from "fs/promises";
 import { existsSync as existsSync30 } from "fs";
-import { dirname as dirname11, join as join33, resolve as resolve21 } from "path";
+import { dirname as dirname12, join as join33, resolve as resolve21 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
   docOutputDuration as docOutputDuration5,
@@ -7926,10 +7926,19 @@ function printChanges(r, changes, protectedIds) {
     r.event({ event: "protected", nodes: protectedIds });
   }
 }
+var DESCRIPTION_MAX = 500;
+function descriptionProblem(desc) {
+  if (desc === void 0) return null;
+  if (!desc.trim())
+    return "--desc is empty: give the sentence that says what the video shows";
+  if (desc.length > DESCRIPTION_MAX)
+    return `--desc is ${desc.length} characters and a vos keeps ${DESCRIPTION_MAX}: shorten it`;
+  return null;
+}
 function takePushRefusal(ask) {
   if (ask.programOnly.length) {
     const list = ask.programOnly.map((f) => `--${f}`).join(", ");
-    return `${list} ${ask.programOnly.length > 1 ? "belong" : "belongs"} to a PROGRAM push (a config.json); a take push reads --vos, --title, --label, --note, --folder, --override and --yes`;
+    return `${list} ${ask.programOnly.length > 1 ? "belong" : "belongs"} to a PROGRAM push (a config.json); a take push reads --vos, --title, --desc, --prompt, --label, --note, --folder, --override and --yes`;
   }
   if (ask.vos !== void 0 && ask.trackedVosId !== null && ask.trackedVosId !== ask.vos)
     return `this take tracks vos ${ask.trackedVosId} (its vos.json), not ${ask.vos}. Drop --vos to push there, or remove vos.json to adopt ${ask.vos} instead`;
@@ -8104,7 +8113,8 @@ async function pushTake(dir, flags, r) {
         ...folderId ? { folderId } : {},
         ...flags.label ? { label: flags.label } : {},
         ...flags.note ? { note: flags.note } : {},
-        ...flags.prompt ? { prompt: flags.prompt } : {}
+        ...flags.prompt ? { prompt: flags.prompt } : {},
+        ...flags.description ? { description: flags.description } : {}
       }
     });
     if (created.status !== 201) {
@@ -8155,14 +8165,18 @@ async function pushTake(dir, flags, r) {
     );
   }
   serverWarnings(pushed.json, (l) => r.log(l));
-  if (flags.prompt) {
+  const words2 = {
+    ...flags.prompt ? { prompt: flags.prompt } : {},
+    ...flags.description ? { description: flags.description } : {}
+  };
+  if (Object.keys(words2).length) {
     const set = await api(ctx, `/vos/${state.vosId}`, {
       method: "PATCH",
-      body: { prompt: flags.prompt }
+      body: words2
     });
     if (set.status !== 200)
       r.warn(
-        `could not set the prompt (${set.status}): ${String(set.json.error ?? "")}${detailLine(set.json)}`
+        `could not set the ${Object.keys(words2).join(" and ")} (${set.status}): ${String(set.json.error ?? "")}${detailLine(set.json)}`
       );
   }
   const version = pushed.json.version;
@@ -8380,6 +8394,7 @@ async function pushTakeClaimable(dir, flags, r) {
   const body = { title, config, doc: docForPush };
   if (state?.vosId) body.remixOfId = state.vosId;
   if (flags.prompt) body.prompt = flags.prompt;
+  if (flags.description) body.description = flags.description;
   if (flags.share) body.share = true;
   const origin = platformOrigin(flags);
   r.log(`creating a claimable push of ${title}\u2026`);
@@ -8918,9 +8933,11 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
   });
   if (pushTarget.kind === "refuse") throw new UsageError(pushTarget.why);
   const vosId = pushTarget.kind === "version" ? pushTarget.vosId : null;
-  if (vosId && (desc || tagsFlag || folderRef)) {
+  const descProblem = descriptionProblem(desc);
+  if (descProblem) throw new UsageError(descProblem);
+  if (vosId && (tagsFlag || folderRef)) {
     throw new UsageError(
-      "--desc/--tags/--folder apply when CREATING a vos. On an existing one: vos folder move <id> --to <folder> for filing; edit title/description/tags on vos.so"
+      "--tags/--folder apply when CREATING a vos. On an existing one: vos folder move <id> --to <folder> for filing; edit tags on vos.so"
     );
   }
   if (vosId) {
@@ -8966,13 +8983,18 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
     if (res.status !== 201)
       throw new Error(apiError(`push version to ${vosId}`, res));
     serverWarnings(res.body, say(r));
-    if (prompt) {
+    const words2 = {
+      ...prompt ? { prompt } : {},
+      ...desc ? { description: desc } : {}
+    };
+    if (Object.keys(words2).length) {
       const set = await apiJson(origin, `/api/vos/${vosId}`, {
         method: "PATCH",
         key,
-        body: { prompt }
+        body: words2
       });
-      if (set.status !== 200) r.warn(apiError("set the prompt", set));
+      if (set.status !== 200)
+        r.warn(apiError(`set the ${Object.keys(words2).join(" and ")}`, set));
     }
     const version = res.body.version ?? {};
     if (typeof version.id === "string") {
@@ -13129,8 +13151,8 @@ async function cmdActions(argv) {
     if (!m) throw new UsageError("--viewport expects WxH, e.g. 1280x720");
     viewport = { width: Number(m[1]), height: Number(m[2]) };
   }
-  const { readFile: readFile19 } = await import("fs/promises");
-  const text = await readFile19(resolve14(input), "utf8");
+  const { readFile: readFile20 } = await import("fs/promises");
+  const text = await readFile20(resolve14(input), "utf8");
   const { records, problems } = parseAgentBrowserLog(text);
   for (const p of problems) r.log(`  ${p}`);
   const result = convertAgentBrowser(records, {
@@ -13167,9 +13189,9 @@ function summary2(result) {
 }
 async function cmdActionsScript(input, flags) {
   const r = createReporter(flags.json === true);
-  const { readFile: readFile19 } = await import("fs/promises");
+  const { readFile: readFile20 } = await import("fs/promises");
   const { shotList, formatShotList } = await import("./shotList-PL7XP6AC.js");
-  const raw = JSON.parse(await readFile19(resolve14(input), "utf8"));
+  const raw = JSON.parse(await readFile20(resolve14(input), "utf8"));
   const errors = validateActions(raw);
   if (errors.length) throw new UsageError(`${input}:
   ${errors.join("\n  ")}`);
@@ -16911,9 +16933,10 @@ async function cmdAudio(argv) {
 }
 
 // src/plugin/look.ts
-import { mkdir as mkdir12 } from "fs/promises";
+import { mkdir as mkdir12, mkdtemp as mkdtemp3, readFile as readFile18, rm as rm6 } from "fs/promises";
 import { existsSync as existsSync27 } from "fs";
-import { join as join30, resolve as resolve20 } from "path";
+import { tmpdir as tmpdir4 } from "os";
+import { dirname as dirname10, join as join30, resolve as resolve20 } from "path";
 import { headersFor, urlSchemeProblem } from "@vosjs/render-core/record";
 function quote(value) {
   return `"${value.replace(/\s+/g, " ").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
@@ -17316,19 +17339,19 @@ async function lookAt(page, url, opts) {
   });
   const ran = [];
   if (!wall || wall.level === "soft") {
-    for (const step2 of opts.steps ?? []) {
-      const all = page.locator(step2.selector);
+    for (const step of opts.steps ?? []) {
+      const all = page.locator(step.selector);
       const target = all.first();
       try {
         await target.waitFor({ state: "visible", timeout: STEP_TIMEOUT_MS });
       } catch {
         throw new UsageError(
-          `--${step2.do} ${step2.selector}: no visible element matches it after ${STEP_TIMEOUT_MS / 1e3} s. Look without the step and take a selector from the list`
+          `--${step.do} ${step.selector}: no visible element matches it after ${STEP_TIMEOUT_MS / 1e3} s. Look without the step and take a selector from the list`
         );
       }
       const count = await all.count();
       const note = count > 1 ? `the first of ${count} matches` : void 0;
-      if (step2.do === "click") {
+      if (step.do === "click") {
         const words2 = await target.evaluate(
           (el) => [
             el.getAttribute("aria-label"),
@@ -17344,25 +17367,37 @@ async function lookAt(page, url, opts) {
         if (word) {
           const label = words2.find((w) => spendWord([w])) ?? word;
           throw new LookRefusal(
-            refusalLine(step2.selector, label.slice(0, 60), word)
+            refusalLine(step.selector, label.slice(0, 60), word)
           );
         }
-        log(`click ${step2.selector}${note ? ` (${note})` : ""}`);
+        log(`click ${step.selector}${note ? ` (${note})` : ""}`);
         await target.click({ timeout: STEP_TIMEOUT_MS });
       } else {
         log(
-          `type ${step2.text.length} chars into ${step2.selector}${note ? ` (${note})` : ""}`
+          `type ${step.text.length} chars into ${step.selector}${note ? ` (${note})` : ""}`
         );
-        await target.fill(step2.text, { timeout: STEP_TIMEOUT_MS });
+        await target.fill(step.text, { timeout: STEP_TIMEOUT_MS });
       }
       ran.push({
-        do: step2.do,
-        selector: step2.selector,
+        do: step.do,
+        selector: step.selector,
         ...note ? { note } : {}
       });
       settled = await settle(page);
     }
   }
+  return inspectPage(page, {
+    url,
+    outDir: opts.outDir,
+    waitMs: opts.waitMs,
+    wall,
+    steps: ran,
+    settled
+  });
+}
+async function inspectPage(page, opts) {
+  const { url, wall, settled } = opts;
+  const ran = opts.steps;
   if (opts.waitMs && opts.waitMs > 0) await page.waitForTimeout(opts.waitMs);
   await mkdir12(opts.outDir, { recursive: true });
   const screenshot = join30(opts.outDir, "look.png");
@@ -17420,7 +17455,27 @@ async function lookAt(page, url, opts) {
     settled
   };
 }
-var USAGE5 = "vos look <url> [--session <name> | --storage-state <file>] [--viewport WxH] [--headed] [--click <selector>]... [--type <selector>=<text>]... [--wait <ms>] [--out <dir>] [--json]";
+var USAGE5 = "vos look <url> [--session <name> | --storage-state <file>] [--viewport WxH] [--headed] [--click <selector>]... [--type <selector>=<text>]... [--wait <ms>] [--out <dir>] [--json]\n       vos look [url] --actions actions.json --until <step id> [--session <name> | --storage-state <file>] [--viewport WxH] [--headed] [--wait <ms>] [--out <dir>] [--json]";
+function untilProblem(given, steps) {
+  if (given.until !== void 0 && given.actions === void 0)
+    return "--until names a step of a script: pass the script with --actions actions.json";
+  if (given.actions === void 0) return null;
+  if (given.clicks)
+    return "--actions walks the script; --click and --type walk by hand. Pass one";
+  if (given.until === void 0)
+    return "--actions needs --until <step id>: the step whose page you want to see";
+  if (!steps) return null;
+  if (steps.some((s) => s.id === given.until)) return null;
+  const ids = steps.map((s) => s.id).filter((id) => !!id);
+  return `--until ${given.until}: no step in ${given.actions} has that id. ${ids.length ? `Its ids: ${ids.join(", ")}` : 'Its steps have no ids; give the step you want an "id"'}`;
+}
+function walkedSteps(steps) {
+  return steps.map((s) => ({
+    do: s.id ? `${s.do} (${s.id})` : s.do,
+    selector: s.selector ?? "",
+    ...s.skipped ? { note: `SKIPPED: ${s.reason ?? "not found"}` } : s.guard ? { note: `guarded (${s.guard}), hovered, not pressed` } : {}
+  }));
+}
 function lookReport(r) {
   const inDialog = r.controls.filter((c) => c.inDialog).length;
   const head = `Looked at ${r.landed} (${r.viewport.width}\xD7${r.viewport.height}): ${r.screenshot}${r.settled ? "" : "\n  note: the page never held still for 0.8 s; looked at it as it was"}`;
@@ -17449,12 +17504,30 @@ async function cmdLook(argv) {
   );
   void multi.click;
   void multi.type;
-  const url = positionals[0];
+  const actionsArg = strFlag(flags, "actions");
+  const untilId = strFlag(flags, "until");
+  const early = untilProblem({
+    actions: actionsArg,
+    until: untilId,
+    clicks: steps.length
+  });
+  if (early) throw new UsageError(early);
+  let actions;
+  if (actionsArg) {
+    actions = await loadLookActions(resolve20(actionsArg));
+    const bad = untilProblem(
+      { actions: actionsArg, until: untilId, clicks: 0 },
+      actions.steps
+    );
+    if (bad) throw new UsageError(bad);
+  }
+  const url = positionals[0] ?? actions?.url;
   if (!url) throw new UsageError(USAGE5);
   const scheme = urlSchemeProblem(url);
   if (scheme) throw new UsageError(scheme);
   const r = createReporter(flags.json === true);
-  const viewport = parseViewport2(strFlag(flags, "viewport"));
+  const viewportFlag = strFlag(flags, "viewport");
+  const viewport = !viewportFlag && actions?.viewport ? actions.viewport : parseViewport2(viewportFlag);
   const outDir = resolve20(strFlag(flags, "out") ?? "look");
   const headed = flags.headed === true;
   const waitRaw = strFlag(flags, "wait");
@@ -17485,6 +17558,22 @@ async function cmdLook(argv) {
     throw new UsageError(e instanceof Error ? e.message : String(e));
   }
   const browserArgs = (multi["browser-arg"] ?? []).filter(Boolean);
+  if (actions && untilId && actionsArg)
+    return lookUntil({
+      r,
+      url,
+      actions,
+      actionsPath: resolve20(actionsArg),
+      untilId,
+      viewport,
+      outDir,
+      waitMs,
+      headed,
+      storageState,
+      sessionName,
+      headers,
+      browserArgs
+    });
   const inContext = async (ctx) => {
     if (Object.keys(headers).length)
       await ctx.route("**/*", async (route) => {
@@ -17531,6 +17620,108 @@ async function cmdLook(argv) {
   );
   return result.wall?.level === "hard" ? EXIT_WALL : EXIT_OK;
 }
+async function loadLookActions(file) {
+  let raw;
+  try {
+    raw = JSON.parse(await readFile18(file, "utf8"));
+  } catch (e) {
+    throw new UsageError(
+      `--actions ${file}: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  const errors = validateActions(raw);
+  if (!errors.length) errors.push(...jsSyntaxProblems(raw));
+  if (errors.length)
+    throw new UsageError(`invalid actions file:
+  ${errors.join("\n  ")}`);
+  return raw;
+}
+async function lookUntil(o) {
+  const { r } = o;
+  const actions = { ...o.actions, viewport: o.viewport };
+  let wall = null;
+  let looked = null;
+  const scratch = await mkdtemp3(join30(tmpdir4(), "vos-look-"));
+  r.log(
+    `walking ${o.actionsPath} to step ${o.untilId} (a rehearsal: guarded steps hovered, never pressed)\u2026`
+  );
+  const browser = await launchBrowser(o.browserArgs, { headless: !o.headed });
+  let rec;
+  try {
+    const walk = (context2) => recordTake(browser, o.url, actions, takePaths(scratch), r.log, {
+      actionsDir: dirname10(o.actionsPath),
+      storageState: o.storageState,
+      headers: o.headers,
+      context: context2,
+      dryRun: true,
+      stopOnHang: true,
+      onEvent: (e) => r.event(e),
+      onArrival: (arrival) => {
+        const verdict = wallVerdict(arrival);
+        if (verdict && verdict.level === "hard") throw new WallError(verdict);
+        if (verdict) r.log(`   WARNING: ${verdict.message}`);
+        wall = verdict;
+        return verdict;
+      },
+      until: {
+        id: o.untilId,
+        at: async (raw) => {
+          const page = raw;
+          const settled = await settle(page);
+          looked = await inspectPage(page, {
+            url: o.url,
+            outDir: o.outDir,
+            waitMs: o.waitMs,
+            wall,
+            steps: [],
+            settled
+          });
+        }
+      }
+    });
+    rec = o.sessionName ? await withSession(o.sessionName, (ctx) => walk(ctx), {
+      headless: !o.headed,
+      viewport: o.viewport
+    }) : await walk(void 0);
+  } finally {
+    await browser.close();
+    await rm6(scratch, { recursive: true, force: true });
+  }
+  const result = looked;
+  const ran = walkedSteps(rec.meta.steps ?? []);
+  const skipped = rec.skipped.length;
+  const teardown = rec.teardown ? `
+  ${teardownLine(rec.teardown)}` : "";
+  if (!result) {
+    const why = rec.stopped ? rec.stopped.reason : "the walk ended before it reached that step";
+    r.done(
+      {
+        ok: false,
+        until: o.untilId,
+        steps: ran,
+        skipped: rec.skipped,
+        ...rec.teardown ? { teardown: rec.teardown } : {}
+      },
+      `NOT LOOKED: step ${o.untilId} was never reached: ${why}.${ran.length ? `
+  walked: ${ran.map((s) => `${s.do}${s.selector ? ` ${s.selector}` : ""}${s.note ? ` (${s.note})` : ""}`).join(", then ")}` : ""}
+  Rehearse the script (vos record --actions ${o.actionsPath} --dry-run) to see where it stops.${teardown}`
+    );
+    return EXIT_USAGE;
+  }
+  const full = { ...result, steps: ran };
+  const warn = skipped ? `
+  WARNING: ${skipped} step${skipped === 1 ? " was" : "s were"} SKIPPED on the way, so this may not be the page the script reaches. Fix ${skipped === 1 ? "it" : "them"}, then look again.` : "";
+  r.done(
+    {
+      ok: skipped === 0 && (!full.wall || full.wall.level === "soft"),
+      until: o.untilId,
+      ...full,
+      ...rec.teardown ? { teardown: rec.teardown } : {}
+    },
+    `${lookReport(full)}${warn}${teardown}`
+  );
+  return skipped ? EXIT_USAGE : EXIT_OK;
+}
 
 // src/plugin/machineCmd.ts
 import { spawnSync as spawnSync4 } from "child_process";
@@ -17548,7 +17739,7 @@ import { chromium as chromium2 } from "playwright";
 
 // src/plugin/machine.ts
 import { existsSync as existsSync28, readFileSync as readFileSync10, readdirSync as readdirSync6, statSync as statSync8 } from "fs";
-import { dirname as dirname10, join as join31 } from "path";
+import { dirname as dirname11, join as join31 } from "path";
 var AGENT_NAMES = [
   "claude",
   "cursor",
@@ -17768,7 +17959,7 @@ function bundledSkillsVersion(dir) {
   }
 }
 function bundledSkillsDir(from) {
-  let dir = dirname10(from);
+  let dir = dirname11(from);
   for (let i = 0; i < 6; i++) {
     const pkg = join31(dir, "package.json");
     if (existsSync28(pkg)) {
@@ -17781,7 +17972,7 @@ function bundledSkillsDir(from) {
       } catch {
       }
     }
-    const up = dirname10(dir);
+    const up = dirname11(dir);
     if (up === dir) break;
     dir = up;
   }
@@ -18503,7 +18694,7 @@ lint-gated, so a bad override fails like a bad doc.json):
                        first ready loop (the house backdrop the studio opens on), or a flat ground offline
 `;
 async function loadActions(file) {
-  const raw = JSON.parse(await readFile18(file, "utf8"));
+  const raw = JSON.parse(await readFile19(file, "utf8"));
   const errors = validateActions(raw);
   if (!errors.length) errors.push(...jsSyntaxProblems(raw));
   if (errors.length)
@@ -18725,7 +18916,7 @@ function reRecord(outDir, flags, r) {
         ...from ? {
           reuse: {
             from,
-            doc: JSON.parse(await readFile18(from, "utf8"))
+            doc: JSON.parse(await readFile19(from, "utf8"))
           }
         } : {}
       });
@@ -18832,7 +19023,7 @@ async function cmdRecord(argv) {
       );
     const hostedActions = await scriptForHost(
       actions,
-      dirname11(resolve21(actionsPath))
+      dirname12(resolve21(actionsPath))
     ).catch((e) => {
       throw new UsageError(e instanceof Error ? e.message : String(e));
     });
@@ -18942,7 +19133,7 @@ async function cmdRecord(argv) {
         sessionName,
         actions,
         (context2) => recordTake(browser2, url, actions, takePaths(outDir), r.log, {
-          actionsDir: dirname11(resolve21(actionsPath)),
+          actionsDir: dirname12(resolve21(actionsPath)),
           storageState,
           headers,
           context: context2,
@@ -19050,7 +19241,7 @@ ${lines.join("\n")}
       sessionName,
       actions,
       (context2) => recordTake(browser, url, actions, paths, r.log, {
-        actionsDir: dirname11(resolve21(actionsPath)),
+        actionsDir: dirname12(resolve21(actionsPath)),
         maxDurationSeconds,
         storageState,
         headers,
@@ -19189,7 +19380,7 @@ async function cmdCreate2(argv) {
       sessionName,
       actions,
       (context2) => recordTake(browser, url, actions, paths, r.log, {
-        actionsDir: dirname11(resolve21(actionsPath)),
+        actionsDir: dirname12(resolve21(actionsPath)),
         maxDurationSeconds,
         storageState,
         headers,
@@ -19316,7 +19507,7 @@ async function cmdPlan(argvIn) {
     );
   const r = createReporter(flags.json === true);
   if (flags.fresh === true) {
-    await rm6(join33(dir, "doc.json"), { force: true });
+    await rm7(join33(dir, "doc.json"), { force: true });
     r.log("note: --fresh discarded the existing doc.json");
   }
   let reuse;
@@ -19329,7 +19520,7 @@ async function cmdPlan(argvIn) {
     }
     reuse = {
       from,
-      doc: JSON.parse(await readFile18(from, "utf8"))
+      doc: JSON.parse(await readFile19(from, "utf8"))
     };
   }
   const style = await resolveStyleRef(flags);
@@ -19801,7 +19992,7 @@ async function resolveDocRef(ref, flags, what) {
     return {
       from: file,
       doc: migrateHostedDoc4(
-        JSON.parse(await readFile18(file, "utf8"))
+        JSON.parse(await readFile19(file, "utf8"))
       )
     };
   }
@@ -19853,7 +20044,7 @@ async function cmdDigest(argv) {
   const take = await loadTake(dir);
   if (!take.doc) throw new UsageError(`${dir} has no doc.json \u2014 run plan first`);
   const transcriptPath = strFlag(flags, "transcript");
-  const transcript = transcriptPath ? parseTranscript(JSON.parse(await readFile18(transcriptPath, "utf8"))) : null;
+  const transcript = transcriptPath ? parseTranscript(JSON.parse(await readFile19(transcriptPath, "utf8"))) : null;
   const style = await resolveStyleRef(flags);
   const noFrames = flags["no-frames"] === true;
   let browser = null;
@@ -19966,7 +20157,7 @@ async function cmdCallout(argv) {
       `no register: put a BRAND.md beside the take (vos brand <url> --out BRAND.md; its bgA and accent are the ground and the accent), or pass --ground #hex --accent #hex`
     );
   const codeFile = strFlag(flags, "code-file");
-  const code = codeFile ? await readFile18(codeFile, "utf8") : strFlag(flags, "code");
+  const code = codeFile ? await readFile19(codeFile, "utf8") : strFlag(flags, "code");
   const words2 = {
     kicker: strFlag(flags, "kicker"),
     title: strFlag(flags, "title"),
@@ -20079,7 +20270,7 @@ async function cmdValidate(argv) {
   }
   if (!isTakeDir(target) && existsSync30(join33(target, "config.json"))) {
     const parsed = JSON.parse(
-      await readFile18(join33(target, "config.json"), "utf8")
+      await readFile19(join33(target, "config.json"), "utf8")
     );
     const pre = preflightConfig(parsed);
     const problems2 = pre.ok ? [] : pre.issues.map((i) => `config.json: ${i}`);
@@ -20237,16 +20428,19 @@ async function cmdPush3(argv) {
   const dir = positionals[0];
   if (!dir)
     throw new UsageError(
-      "vos push <take> [--vos|--title|--label|--note|--prompt|--folder|--override|--yes|--key|--api|--bake|--claimable [--share]]"
+      "vos push <take> [--vos|--title|--desc|--label|--note|--prompt|--folder|--override|--yes|--key|--api|--bake|--claimable [--share]]"
     );
   const refusal = takePushRefusal({
     vos: strFlag(flags, "vos"),
     trackedVosId: readSyncState(resolve21(dir))?.vosId ?? null,
-    programOnly: ["slug", "desc", "tags", "base", "remix-of", "still"].filter(
+    programOnly: ["slug", "tags", "base", "remix-of", "still"].filter(
       (name) => hasFlag(flags, name)
     )
   });
   if (refusal) throw new UsageError(refusal);
+  const description = strFlag(flags, "desc");
+  const descProblem = descriptionProblem(description);
+  if (descProblem) throw new UsageError(descProblem);
   const r = createReporter(flags.json === true);
   if (flags.claimable === true) {
     const iterating = ["vos", "folder", "override", "base"].filter(
@@ -20263,6 +20457,7 @@ async function cmdPush3(argv) {
         origin: strFlag(flags, "origin"),
         title: strFlag(flags, "title"),
         prompt: strFlag(flags, "prompt"),
+        description,
         share: flags.share === true,
         bake: flags.bake === true
       },
@@ -20293,6 +20488,7 @@ reference and the only credential.`
       folder: strFlag(flags, "folder"),
       overrides,
       prompt: strFlag(flags, "prompt"),
+      description,
       bake: flags.bake === true
     },
     r
@@ -20684,4 +20880,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-HDJFCTOG.js.map
+//# sourceMappingURL=chunk-DM7ADA77.js.map