@vosjs/cli 0.81.1 → 0.83.0

package/README.md

@@ -190,7 +190,7 @@ 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`).
 
-**`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`. 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.
+**`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
 "setup": [
@@ -203,9 +203,12 @@ It writes `<out>/look.png` (the viewport; `--out look` by default) and lists eve
 
 **`teardown`: the steps that run after it.** A flow that CREATES something in the account (an API key, a project, an invite) creates it on every rehearsal and every take, since `--dry-run` clicks for real. `teardown: [...]` beside `setup` removes it again: the same verbs and the same rules (a `{ "env": "NAME" }` text, no literal in a password field, http and https only), run off camera once the screencast has stopped, on the take's own page and session, so nothing of it is captured or lands in `meta.steps`. It runs after a rehearsal too, and when the take stops early (a failed `await`, `--strict` on a page that stopped answering, the cap) or throws once its first step ran; not when the take never began (a setup that failed, a wall). The steps together get 60 s. A teardown never fails the take or changes the exit code: it stops at the first step that fails, the done event carries `teardown: { ran, of, failed?: { step, do, selector?, error } }`, and the summary says `teardown: 3 step(s) ran` or `TEARDOWN FAILED at teardown[1] (click #confirm): <reason>. What the take created may still be in the product; remove it by hand.` A `{ env }` the shell does not hold refuses the take before it begins, since the take would create what its teardown cannot remove.
 
+**`if`: a guard for either list.** `{ "do": "if", "selector": "…" }` looks for its selector (3 s, or its `ms`): on the page, the steps after it run; not on the page, they are skipped and the list ends there, which is never a failure. A take that deletes on camera what it created, and keeps a teardown as the net for a take that stops early, starts the undoing with one, so a good take says `teardown: nothing to undo, <selector> is not on the page` instead of a failure; the done event carries `skipped: { step, selector, rest }`. A setup that signs in guards its sign-in the same way (`if` the email field), so a session already signed in passes. A step that fails after a guard still fails.
+
 ```json
 "teardown": [
   { "do": "goto", "url": "http://localhost:3000/settings/keys" },
+  { "do": "if", "selector": "[data-testid=key-row]:first-child" },
   { "do": "click", "selector": "[data-testid=key-row]:first-child button[aria-label=Revoke]" },
   { "do": "click", "selector": "role=button[name=\"Revoke key\"]" }
 ]
@@ -452,6 +455,8 @@ Not sure of a selector? `vos look <url>` (with the take's `--session` or `--stor
 
 **Pinned layers.** A layer ABOUT something on the page names it, and the lowering keeps the two together: `"pin": { "step": "copy", "side": "auto", "mark": "ring", "leader": true }` on any overlay kind places the layer a gap off one side of that step's element and carries it with the element as the camera moves (the layer keeps its screen size; only its place follows). One of `step` (a recorder step's `id`, else its index), `press` (SOURCE seconds; the nearest press names the element, for a human recording) or `rect` (video fractions) names the referent. `side` is `auto` (the first of right, left, below, above whose box fits inside the frame through the layer's life) or a side by name; `gap` is design px (24); `mark` is `ring` or `underline`, a standing highlight on the referent for the layer's life; `leader` draws a hairline from the layer to the referent; `color` is their ink. `transform.x/y` stay the fallback for a pin that cannot resolve, and `vos validate` says why (an unknown step, a step that touched nothing, a scroll inside the layer's window). A layer that cannot name its referent is a caption: place it in the margin, never over the app.
 
+**How long a caption stays.** The captions `vos plan --motion` and `--captions` land are about their steps: each lands as its step begins and leaves as the step ends, or once its words are read when that is later (17 characters a second, the subtitle standard, 1.2 to 3 s), so it never lingers over the steps after it. A caption whose words outlast its step is named in the done line with how long it stays past the step; shorter words, or more time on the step (its `ms`, then a re-record), let it leave with it. Cutting its duration instead only takes the time its words need. It gives way to the next caption 0.1 s before it and never outlives the clip it starts in; one with too little room to be read is dropped and named in the done line, with the room it needs.
+
 **Captions anchored to a step.** A layer's TIME can name a step the way a pin names its place: `"anchor": { "step": "share", "media": "m1", "at": "end", "offset": 0.2 }` starts the layer where that step plays in the cut. The lowering maps the step's moment (its `tStart`, or `tEnd` with `at: "end"`, in `meta.steps` of the media `media` names; absent = the primary) through the segments, speed spans and freezes exactly as a source-anchored span is mapped, then adds `offset` in OUTPUT seconds, so a trim, a speed change or a re-record moves the caption with its step and nobody recomputes a `start`. `start` is the fallback when the step is missing, skipped or cut out, and an anchored layer may leave it out: one whose step then resolves nowhere plays nowhere, which `vos validate` refuses, naming the step. `duration` is the layer's own; on a cut that replays the step's seconds the layer starts in the pass where the step plays the longest (the first on a tie), so a caption about a step lands in the main play rather than a short cold open. A text layer's `{elapsed}` fills with the anchored step's off-camera wait when the recorder kept one (the entry of `meta.skips` that names it, else `offCameraMs` on the step; never a step's own `ms`, which is its reading time), and a step that waited for nothing itself (the beat that lands after an await) reads the nearest earlier wait on its media, which validate notes, as a rounded duration: `"{elapsed} later"` renders `12 minutes later`. `vos validate` says when an anchor cannot resolve (and which fallback plays), when `{elapsed}` has no wait at or before its step to fill from, when two captions are on screen at the same time, naming both, and when a layer anchored to one media's step starts over another media's footage (a caption landed after its gesture, then the footage after that step trimmed away). A document without an anchor lowers exactly as before. Not the re-record `anchor` on spans, which only `vos plan --reuse` reads.
 
 **Image and video overlays.** Media kinds on the same lane: `{ "id": "m0", "kind": "image" | "video", "start": 2, "duration": 4, "key": "/logo.png", "width": 0.35, "radius": 12, "opacity": 1, "loop": false, "transform": { … } }`. `key` is a file inside the take directory (`"/logo.png"`) or a URL; `width` is a fraction of the frame width, height follows the media's aspect; corners in design px. Video time is clip-local and muted by design; soundtracks belong to `doc.audio`.

package/dist/{chunk-S3RI2SHH.js → chunk-5VGIQKVT.js}

@@ -4150,6 +4150,7 @@ import {
   migrateMotion,
   momentOutputs as momentOutputs2,
   ratedSegments as ratedSegments4,
+  resolveAnchor as resolveLayerAnchor,
   sameMedia,
   spanOutputExtent as spanOutputExtent3
 } from "@vosjs/studio-core";
@@ -4158,6 +4159,14 @@ import {
 var CAPTION_MAX = 3;
 var CAPTION_MIN = 1.2;
 var CAPTION_GAP = 0.1;
+var READ_CHARS_PER_SECOND = 17;
+function readingSeconds(text) {
+  const chars = text.trim().replace(/\s+/g, " ").length;
+  return Math.min(
+    CAPTION_MAX,
+    Math.max(CAPTION_MIN, chars / READ_CHARS_PER_SECOND)
+  );
+}
 function fitCaptions(items, slotOf, opts = {}) {
   const max = opts.max ?? CAPTION_MAX;
   const min = opts.min ?? CAPTION_MIN;
@@ -4170,7 +4179,11 @@ function fitCaptions(items, slotOf, opts = {}) {
     const { item, slot } = ordered[i];
     const clipRoom = slot.end - slot.start;
     const nextRoom = nextStart - gap - slot.start;
-    const duration = Math.min(max, clipRoom, nextRoom);
+    const ownRoom = slot.until === void 0 ? Infinity : Math.max(
+      slot.until - slot.start,
+      slot.text === void 0 ? min : readingSeconds(slot.text)
+    );
+    const duration = Math.min(max, clipRoom, nextRoom, ownRoom);
     if (duration < min - 1e-9) {
       dropped.unshift({
         item,
@@ -4178,11 +4191,19 @@ function fitCaptions(items, slotOf, opts = {}) {
       });
       continue;
     }
-    kept.unshift({ item, duration: +duration.toFixed(3) });
+    const held = slot.until === void 0 ? 0 : duration - (slot.until - slot.start);
+    kept.unshift({
+      item,
+      duration: +duration.toFixed(3),
+      ...held > 0.05 ? { held: +held.toFixed(2) } : {}
+    });
     nextStart = slot.start;
   }
   return { kept, dropped };
 }
+function heldLine(label, held) {
+  return `${label} stays ${held.toFixed(2)}s past its step to be read; to let it leave with the step, shorten its words (17 characters read in a second) or give its step more time (its ms, then record again). Do not cut its duration: the words need that time`;
+}
 
 // src/plugin/moments.ts
 import {
@@ -4343,6 +4364,7 @@ function proposeMotion(input, opts) {
   const { words: words2, launch, catalog } = opts;
   const notes = [];
   const skipped = [];
+  const held = [];
   const footage = outputLength(doc);
   const range2 = [0, footage];
   const entrance = launch.entrance;
@@ -4459,15 +4481,37 @@ function proposeMotion(input, opts) {
         (s) => c.id !== void 0 && s.id === c.id || s.step === c.step
       );
       if (!step || step.skipped) continue;
-      const t = stepOutputTime(rated, step, 0.2);
+      const ref = step.id ?? step.step;
+      const t = resolveLayerAnchor(doc, { step: ref, at: "start" }, rated).start;
       if (t === null || t < 0 || t >= footage) continue;
-      beats.push({ caption: c, t: +t.toFixed(3) });
+      const until = resolveLayerAnchor(
+        doc,
+        { step: ref, at: "end" },
+        rated
+      ).start;
+      beats.push({
+        caption: c,
+        t: +t.toFixed(3),
+        ...until !== null ? { until } : {}
+      });
     }
-    const fit = fitCaptions(beats, (b) => ({ start: b.t, end: footage }), {
-      max: CAPTION_BEAT_MAX
-    });
+    const fit = fitCaptions(
+      beats,
+      (b) => ({
+        start: b.t,
+        end: footage,
+        ...b.until !== void 0 ? { until: b.until } : {},
+        text: b.caption.caption
+      }),
+      { max: CAPTION_BEAT_MAX }
+    );
     for (const { item, why } of fit.dropped)
       skipped.push(`caption for step ${item.caption.step}: ${why}`);
+    for (const k of fit.kept)
+      if (k.held)
+        held.push(
+          heldLine(`the caption for step ${k.item.caption.step}`, k.held)
+        );
     for (const { item, duration } of fit.kept)
       captionClips.push(
         houseCaption(
@@ -4531,7 +4575,7 @@ function proposeMotion(input, opts) {
     if (times.length) notes.push(`${times.length} click sound(s)`);
   }
   doc.audio = clips;
-  return { doc, notes, skipped };
+  return { doc, notes, skipped, held };
 }
 function destinationMechanics(d, doc) {
   const set = [];
@@ -6754,7 +6798,7 @@ import {
 import {
   docFreezes,
   ratedSegments as ratedSegments6,
-  resolveAnchor as resolveLayerAnchor
+  resolveAnchor as resolveLayerAnchor2
 } from "@vosjs/studio-core";
 var MIN_SPAN = 0.15;
 var AFTER_STEP = 1;
@@ -7050,7 +7094,7 @@ function retimeOverlays(prev, next, report) {
   };
   return overlays.map((o) => {
     if (o.anchor && typeof o.anchor === "object") {
-      const r = resolveLayerAnchor(next, o.anchor, newPieces);
+      const r = resolveLayerAnchor2(next, o.anchor, newPieces);
       if (r.start === null) {
         report.flagged.push(
           o.start === void 0 ? `overlay ${o.id}: anchored to step ${String(o.anchor.step)}, which is missing, skipped or cut in the new recording \u2014 it has no start to fall back to, so it plays nowhere; re-anchor it or give it a start` : `overlay ${o.id}: anchored to step ${String(o.anchor.step)}, which is missing, skipped or cut in the new recording \u2014 it plays at its fallback ${o.start.toFixed(2)}s; re-anchor or re-place it`
@@ -7337,7 +7381,11 @@ async function planTake(dir, opts = {}) {
   if (opts.motion && (fresh || opts.motion.again)) {
     const proposed = proposeMotion(doc, opts.motion);
     doc = proposed.doc;
-    motion = { notes: proposed.notes, skipped: proposed.skipped };
+    motion = {
+      notes: proposed.notes,
+      skipped: proposed.skipped,
+      held: proposed.held
+    };
   }
   if (opts.still != null) doc.still = opts.still;
   await writeJson(take.paths.doc, doc, true);
@@ -14659,6 +14707,7 @@ import {
   docMediaList as docMediaList2,
   findStep as findStep3,
   mediaKey,
+  overlayPlainText,
   ratedSegments as ratedSegments8,
   resolveAnchor as resolveAnchor5,
   segmentOutputExtents as segmentOutputExtents2
@@ -14744,7 +14793,12 @@ function captionOf(step, actions, script, recorded = []) {
 }
 var safeId = (v) => String(v).replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "step";
 function landStepCaptions(doc, actions, opts = {}) {
-  const report = { landed: [], skipped: [], uncaptioned: [] };
+  const report = {
+    landed: [],
+    skipped: [],
+    held: [],
+    uncaptioned: []
+  };
   const mine = (o) => !opts.only || opts.only.has(mediaKey(o.anchor?.media));
   const kept = (doc.overlays ?? []).filter(
     (o) => o.from !== STEP_CAPTIONS_FROM || !mine(o)
@@ -14763,6 +14817,7 @@ function landStepCaptions(doc, actions, opts = {}) {
   };
   const ends = /* @__PURE__ */ new Map();
   const labels = /* @__PURE__ */ new Map();
+  const untils = /* @__PURE__ */ new Map();
   const spoken = (media, step, steps) => kept.some((o) => {
     if (o.kind !== "text" || o.preset !== "caption") return false;
     if (o.anchor && mediaKey(o.anchor.media) === media)
@@ -14815,6 +14870,8 @@ function landStepCaptions(doc, actions, opts = {}) {
         from: STEP_CAPTIONS_FROM
       };
       ends.set(clip, end);
+      const stepEnd = resolveAnchor5(doc, { ...anchor, at: "end" }, rated);
+      if (stepEnd.start !== null) untils.set(clip, stepEnd.start);
       labels.set(clip, label);
       fresh.push(clip);
       report.landed.push({
@@ -14828,12 +14885,17 @@ function landStepCaptions(doc, actions, opts = {}) {
   }
   const fit = fitCaptions(fresh, (c) => ({
     start: c.start,
-    end: ends.get(c) ?? footageEnd
+    end: ends.get(c) ?? footageEnd,
+    ...untils.has(c) ? { until: untils.get(c) } : {},
+    ...c.kind === "text" ? { text: overlayPlainText(c) } : {}
   }));
   for (const { item, why } of fit.dropped) {
     report.skipped.push(`${labels.get(item) ?? item.id}: ${why}`);
     report.landed = report.landed.filter((l) => l.id !== item.id);
   }
+  for (const k of fit.kept)
+    if (k.held)
+      report.held.push(heldLine(labels.get(k.item) ?? k.item.id, k.held));
   const landedClips = fit.kept.map(({ item, duration }) => {
     item.duration = duration;
     return item;
@@ -16335,6 +16397,7 @@ async function cmdJoin(argv) {
   let captions = null;
   if (withCaptions) {
     captions = landStepCaptions(plan.doc, plan.actions, { only });
+    for (const line of captions.held) plan.notes.push(line);
     for (const k of captions.uncaptioned)
       plan.notes.push(
         `no step in ${labelOf.get(k) ?? `media ${k}`} carries a caption`
@@ -16462,7 +16525,7 @@ import {
   freezeOutputExtents,
   mediaKey as mediaKey5,
   migrateMotion as migrateMotion4,
-  overlayPlainText,
+  overlayPlainText as overlayPlainText2,
   longestOutputExtent as longestOutputExtent3,
   ratedSegments as ratedSegments11,
   resolveOverlayAnchors as resolveOverlayAnchors2,
@@ -16576,7 +16639,7 @@ function takeTimeline(rawDoc, actions = /* @__PURE__ */ new Map()) {
     const start = o.start;
     if (start === void 0) return [];
     const raw = rawById.get(o.id);
-    const text = o.kind === "text" ? overlayPlainText(o) : o.kind === "html" ? void 0 : o.key;
+    const text = o.kind === "text" ? overlayPlainText2(o) : o.kind === "html" ? void 0 : o.key;
     return [
       {
         id: o.id,
@@ -19328,7 +19391,8 @@ async function cmdPlan(argvIn) {
   const zoomManual = s.doc.zoom.length - zoomAuto;
   const captionLines = captions ? `
   ${captions.landed.length} step caption${captions.landed.length === 1 ? "" : "s"} anchored to their steps` + (captions.skipped.length ? `
-  not landed: ${captions.skipped.join("; ")}` : "") + (captions.uncaptioned.length ? `
+  not landed: ${captions.skipped.join("; ")}` : "") + (captions.held.length ? `
+  ${captions.held.join("\n  ")}` : "") + (captions.uncaptioned.length ? `
   no step in ${captions.uncaptioned.length === 1 && captions.uncaptioned[0] === "" ? "this take" : captions.uncaptioned.map((m) => m ? `media ${m}` : "the primary").join(", ")} carries a caption` : "") : "";
   const layoutLines = s.layout ? `
   layout from ${s.styleFrom}: ${[
@@ -19339,7 +19403,8 @@ async function cmdPlan(argvIn) {
     ${s.layout.notes.join("\n    ")}` : "") : "";
   const motionLines = s.motion ? (s.motion.notes.length ? `
   proposed: ${s.motion.notes.join(", ")}` : "") + (s.motion.skipped.length ? `
-  not proposed: ${s.motion.skipped.join("; ")}` : "") : "";
+  not proposed: ${s.motion.skipped.join("; ")}` : "") + (s.motion.held.length ? `
+  ${s.motion.held.join("\n  ")}` : "") : "";
   const reuseLines = s.reuse ? `
   reused ${s.reuse.from}: ${s.reuse.anchored} anchored + ${s.reuse.mapped} mapped span(s)` + (s.reuse.flagged.length ? `
   flagged:
@@ -20617,4 +20682,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-S3RI2SHH.js.map
+//# sourceMappingURL=chunk-5VGIQKVT.js.map