@nodegx/mcp 0.2.6 → 0.2.8

package/dist/render-harness/data/node-catalog.json

@@ -47268,7 +47268,7 @@
           "always: the size it holds now, a bare number read in the unit it held; drawn at the next paint"
         ],
         "visible": [
-          "always: shown or hidden at the next paint, its space kept; hidden, a Focus does not reach it"
+          "always: shown or hidden at once, its space kept; hidden, a Focus does not reach it"
         ]
       },
       "warnings": {
@@ -49453,7 +49453,7 @@
           "always: the page, or the scrolling Group holding it, scrolls until the box can be seen"
         ],
         "visible": [
-          "always: shown or hidden at the next paint, its space kept; hidden, a Focus does not reach it"
+          "always: shown or hidden at once, its space kept; hidden, a Focus does not reach it"
         ]
       },
       "warnings": {
@@ -52032,11 +52032,12 @@
         ],
         "items": [
           "nothing handed (undefined): the list it has stays",
+          "the value is still the placed node's seed and the list does not offer it: the list is kept, and the value is cleared to '' and sent",
           "otherwise: the list is kept as handed and drawn at the next paint; the value stays, so a list handed again keeps the pick"
         ],
         "value": [
           "null: ignored",
-          "the value it already holds, as text: nothing",
+          "the value it already holds, as text: nothing (it is no longer the seed)",
           "a change: kept as text, Value follows, and the list selects it at the next paint if it names an option — Changed does not fire (only a person's pick fires it)"
         ],
         "mounted": [
@@ -52064,7 +52065,7 @@
           "always: the size it holds now, a bare number read in the unit it held; drawn at the next paint"
         ],
         "visible": [
-          "always: shown or hidden at the next paint, its space kept; hidden, a Focus does not reach it"
+          "always: shown or hidden at once, its space kept; hidden, a Focus does not reach it"
         ]
       },
       "warnings": {
@@ -54246,7 +54247,7 @@
           "always: the page, or the scrolling Group holding it, scrolls until the button can be seen"
         ],
         "visible": [
-          "always: shown or hidden at the next paint, its space kept; hidden, it takes no click and a Focus does not reach it"
+          "always: shown or hidden at once, its space kept; hidden, it takes no click and a Focus does not reach it"
         ]
       },
       "warnings": {
@@ -56651,7 +56652,7 @@
           "always: the size it holds now, a bare number read in the unit it held; drawn at the next paint"
         ],
         "visible": [
-          "always: shown or hidden at the next paint, its space kept; hidden, a Focus does not reach it"
+          "always: shown or hidden at once, its space kept; hidden, a Focus does not reach it"
         ]
       },
       "warnings": {
@@ -59521,7 +59522,7 @@
           "always: the size it holds now, a bare number read in the unit it held; drawn at the next paint"
         ],
         "visible": [
-          "always: shown or hidden at the next paint, its space kept; hidden, a Focus does not reach it"
+          "always: shown or hidden at once, its space kept; hidden, a Focus does not reach it"
         ],
         "opacity": [
           "always: how see-through it is; at exactly 0 it takes no pointer, and an act goes to what is behind it"
@@ -64363,7 +64364,7 @@
           },
           "isSignal": false,
           "default": false,
-          "description": "Whether a request with no valid session token is allowed to run this function at all"
+          "description": "Whether a request with no valid session token is allowed to run this function at all. A run the app starts itself — a schedule, a row change, a run from Studio — is always allowed and sees nobody signed in; a webhook is a request like any other"
         },
         {
           "name": "params",
@@ -64417,7 +64418,7 @@
           "group": "Request",
           "plug": "output",
           "type": {
-            "name": "boolean"
+            "name": "string"
           },
           "isSignal": false,
           "description": "Id of the user the session token resolved to, and blank for an unauthenticated request"

package/dist/render-harness/drive-steps.js

@@ -654,6 +654,80 @@ var require_src = __commonJS({
     }
   }
 
+  // P112-OWN019-LOOKBLIND / OWN-026 \u2014 text a person cannot read against what is painted behind it. Large 4's number pad
+  // set white digits on a #FAF5FF button (1.07:1) and it survived five changes: the model tapped the keys, read
+  // "Correct!" and never saw that nobody could read them, because nothing here measured contrast. The ground is the
+  // text's ancestors' background colours composited from the first opaque one (white under them all, as a browser
+  // paints), the ink is the text's colour faded by every ancestor's opacity, and the ratio is WCAG's. It abstains,
+  // counted, wherever ancestors are not what is painted underneath: a background image or gradient, a text shadow, an
+  // SVG text. A disabled or aria-hidden control is exempt (WCAG 1.4.3's inactive components). Known limit: a sibling
+  // laid over the text by position is not an ancestor, so it is not seen. Raw pairs here; the judgement is summarise's.
+  layout.lowContrast = [];
+  layout.contrastChecked = 0;
+  layout.contrastAbstained = 0;
+  const CONTRAST_FLOOR = 3;
+  {
+    const parseColor = (c) => {
+      const m = String(c || '').match(/rgba?\\(([^)]+)\\)/);
+      if (!m) return null;
+      const p = m[1].split(/[ ,\\/]+/).filter(Boolean).map(Number);
+      if (p.length < 3 || p.some((x) => isNaN(x))) return null;
+      return { r: p[0], g: p[1], b: p[2], a: p.length > 3 ? p[3] : 1 };
+    };
+    const over = (top, under) => ({ r: top.r * top.a + under.r * (1 - top.a), g: top.g * top.a + under.g * (1 - top.a), b: top.b * top.a + under.b * (1 - top.a), a: 1 });
+    const lum = (c) => {
+      const f = (x) => { const v = x / 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+      return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b);
+    };
+    const contrastOf = (a, b) => { const x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); };
+    const hexOf = (c) => '#' + [c.r, c.g, c.b].map((v) => Math.round(v).toString(16).padStart(2, '0')).join('');
+    const inactive = (e) => e.disabled === true || (typeof e.getAttribute === 'function' && (e.getAttribute('aria-disabled') === 'true' || e.getAttribute('aria-hidden') === 'true'));
+    // What is behind the text, or null to abstain; 'exempt' for an inactive control.
+    const groundOf = (el) => {
+      const stack = [];
+      let opacity = 1;
+      for (let e = el; e; e = e.parentElement) {
+        if (inactive(e)) return 'exempt';
+        const cs = styleOf(e);
+        if (!cs) break;
+        const image = cs.backgroundImage;
+        if (image && image !== 'none' && !/^url\\("data:image\\/svg/.test(image)) return null;
+        const bg = parseColor(cs.backgroundColor);
+        const o = Number(cs.opacity);
+        if (o >= 0 && o <= 1) opacity *= o;
+        if (bg && bg.a > 0) {
+          stack.push(bg);
+          if (bg.a >= 0.999) break;
+        }
+      }
+      let g = { r: 255, g: 255, b: 255, a: 1 };
+      while (stack.length) g = over(stack.pop(), g);
+      return { ground: g, opacity };
+    };
+    const pairs = new Map();
+    for (const el of textEls) {
+      if (el.namespaceURI && el.namespaceURI !== 'http://www.w3.org/1999/xhtml') { layout.contrastAbstained += 1; continue; }
+      const cs = styleOf(el);
+      const fill = parseColor(cs.webkitTextFillColor);
+      const fg = fill || parseColor(cs.color);
+      if (!fg || fg.a === 0) continue;
+      if (cs.textShadow && cs.textShadow !== 'none') { layout.contrastAbstained += 1; continue; }
+      const at = groundOf(el);
+      if (at === 'exempt') continue;
+      if (at === null) { layout.contrastAbstained += 1; continue; }
+      if (at.opacity < 0.05) continue;
+      const ink = over({ r: fg.r, g: fg.g, b: fg.b, a: fg.a * at.opacity }, at.ground);
+      const ratio = Math.round(contrastOf(ink, at.ground) * 100) / 100;
+      layout.contrastChecked += 1;
+      if (ratio >= CONTRAST_FLOOR) continue;
+      const key = hexOf(ink) + '|' + hexOf(at.ground);
+      const seen = pairs.get(key);
+      if (seen) seen.count += 1;
+      else pairs.set(key, { text: el.textContent.trim().slice(0, 40), fg: hexOf(ink), bg: hexOf(at.ground), ratio, size: round(parseFloat(cs.fontSize) || 0), weight: String(cs.fontWeight || ''), cls: cls(el), count: 1 });
+    }
+    layout.lowContrast = [...pairs.values()].sort((a, b) => a.ratio - b.ratio).slice(0, 10);
+  }
+
   const contentBottom = visible.reduce((lowest, el) => {
     const r = el.getBoundingClientRect();
     return r.width > 0 && r.height > 0 && r.bottom > lowest ? r.bottom : lowest;
@@ -821,7 +895,12 @@ var require_src = __commonJS({
        * P112-OWN019-LETTEREDGE (Richard 2026-10-15, TL2's hero). Words within 3 px of the inner left or right edge of the
        * box that frames them (a border or a fill) — a letter in an outlined chip set left because its Text stretched.
        */
-      TextAgainstEdge: "text-against-edge"
+      TextAgainstEdge: "text-against-edge",
+      /**
+       * P112-OWN019-LOOKBLIND (OWN-026's number pad: white digits on #FAF5FF, 1.07:1, through five changes). Text under 3:1
+       * against the background composited behind it — unreadable to anyone, and invisible to an agent that only reads text.
+       */
+      LowContrastText: "low-contrast-text"
     };
     var SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
     var ROW_GAP_MIN_TALLEST = 48;
@@ -867,6 +946,7 @@ var require_src = __commonJS({
       const findings = [];
       const add = (f) => findings.push(f);
       let controlsJudged = false;
+      const contrastPairs = /* @__PURE__ */ new Map();
       for (const [name, v] of Object.entries(viewports)) {
         if (!v || v.error) continue;
         const isDesktop = v.requested.width >= DESKTOP_WIDTH;
@@ -1112,6 +1192,12 @@ var require_src = __commonJS({
             evidence: edges.slice(0, 6)
           });
         }
+        for (const c of v.layout && v.layout.lowContrast || []) {
+          const key = c.fg + "|" + c.bg;
+          const prev = contrastPairs.get(key);
+          if (!prev) contrastPairs.set(key, { ...c, viewport: name });
+          else if (c.count > prev.count) prev.count = c.count;
+        }
         if (v.consoleErrors && v.consoleErrors.length) {
           add({
             code: RenderFinding.ConsoleError,
@@ -1122,6 +1208,17 @@ var require_src = __commonJS({
           });
         }
       }
+      if (contrastPairs.size) {
+        const worst = [...contrastPairs.values()].sort((a, b) => a.ratio - b.ratio);
+        const named = worst.slice(0, 3).map((c) => `"${c.text}" ${c.fg} on ${c.bg}, ${c.ratio}:1${c.count > 1 ? ` (and ${c.count - 1} more like it)` : ""}`);
+        add({
+          code: RenderFinding.LowContrastText,
+          severity: "warning",
+          viewport: worst[0].viewport,
+          message: `${plural(worst.length, "colour pair", "colour pairs")} of text ${worst.length === 1 ? "reads" : "read"} under 3:1 against what is behind ${worst.length === 1 ? "it" : "them"}, so a person cannot read ${worst.length === 1 ? "it" : "them"}: ${named.join("; ")}. Pressing it still works, so a drive will not notice: set the text's colour or its background from the style vocabulary so they differ in lightness, not only in hue. Look at the ${worst[0].viewport} screenshot.`,
+          evidence: worst.slice(0, 6)
+        });
+      }
       const seen = /* @__PURE__ */ new Set();
       const unique = findings.filter((f) => {
         const key = `${f.code}|${f.viewport}|${f.message}`;
@@ -2087,6 +2184,32 @@ var require_render_report = __commonJS({
         }
       };
     }
+    var PAGE_ANSWER_MS = Number(process.env.NODEGX_RENDER_PAGE_ANSWER_MS) || 3e4;
+    async function pageAnswers(attaching, chromePath) {
+      const neverAnswered = (refused) => {
+        const message = "Chrome started (its debugging port opened) but its page " + (refused ? `refused the connection (${refused.message || refused}). ` : `never answered within ${Math.round(PAGE_ANSWER_MS / 1e3)} s. `) + `That is what Chrome does inside another sandbox (an agent harness that runs commands under sandbox-exec, a container): its own sandbox cannot start and its pages crash. Run the render outside that sandbox, or set CHROME_PATH to a script that starts ${chromePath} with --no-sandbox.`;
+        const error = new Error(message);
+        error.problems = [message];
+        error.actionable = true;
+        return error;
+      };
+      if (!attaching) throw neverAnswered();
+      let timer;
+      const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(neverAnswered()), PAGE_ANSWER_MS);
+      });
+      try {
+        const answered = attaching.then(
+          async (tab) => (await evaluate(tab.client, "1"), tab),
+          (refused) => {
+            throw neverAnswered(refused);
+          }
+        );
+        return await Promise.race([answered, deadline]);
+      } finally {
+        clearTimeout(timer);
+      }
+    }
     async function withRenderedPage2(options, fn) {
       const { projectDir, backendPort, editorTokens = false, chromeArgs = [], beforeBoot } = options;
       reapOrphanedRenderProcesses();
@@ -2186,7 +2309,10 @@ var require_render_report = __commonJS({
         if (!targets) throw new Error(`Chrome never opened a debugging port (${pre.chrome}).`);
         const target = targets.find((t) => t.type === "page");
         const settles = [];
-        const main2 = await attachTab({ wsUrl: target.webSocketDebuggerUrl, servePort, settles });
+        const main2 = await pageAnswers(
+          target ? attachTab({ wsUrl: target.webSocketDebuggerUrl, servePort, settles }) : void 0,
+          pre.chrome
+        );
         client = main2.client;
         const openTab = async (label) => {
           if (!browserClient) {
@@ -2251,9 +2377,11 @@ var require_render_report = __commonJS({
         editorTokens = false,
         renderRoutedPages = true,
         page: requestedPage,
-        concurrency = PAGE_TABS
+        concurrency = PAGE_TABS,
+        imageBudget
       } = options;
       const started = Date.now();
+      const imageBytesEach = imageBudget ? Math.floor(imageBudget / Math.max(1, viewports.length)) : 0;
       const routes = routedPages2(projectDir);
       let focus;
       if (requestedPage !== void 0) {
@@ -2285,24 +2413,45 @@ var require_render_report = __commonJS({
         if (focusedOffStart) await page.navigate(focus.url);
         const measured = {};
         const screenshots = [];
+        const take = (vp, client, format, height, quality) => client.send("Page.captureScreenshot", {
+          format,
+          ...format === "jpeg" ? { quality } : {},
+          captureBeyondViewport: screenshot === "full",
+          optimizeForSpeed: true,
+          ...screenshot === "full" ? { clip: { x: 0, y: 0, width: vp.width, height, scale: deviceScaleFactor } } : {}
+        });
         const capture = async (vp, raw, component, subject2, client = page.client) => {
-          const shot = await client.send("Page.captureScreenshot", {
-            format: "png",
-            captureBeyondViewport: screenshot === "full",
-            optimizeForSpeed: true,
-            ...screenshot === "full" ? {
-              clip: {
-                x: 0,
-                y: 0,
-                width: vp.width,
-                // Chrome refuses beyond 16384px; a page taller than that is
-                // already the finding.
-                height: Math.min(raw.pageHeight, 16384),
-                scale: deviceScaleFactor
-              }
-            } : {}
-          });
-          return { name: vp.name, page: component, subject: subject2, mimeType: "image/png", base64: shot.data };
+          const fullHeight = Math.min(raw.pageHeight, 16384);
+          const shot = await take(vp, client, "png", fullHeight);
+          const base = { name: vp.name, page: component, subject: subject2 };
+          if (!imageBytesEach || shot.data.length <= imageBytesEach) return { ...base, mimeType: "image/png", base64: shot.data };
+          return { ...base, ...await fitted(vp, client, fullHeight) };
+        };
+        const fitted = async (vp, client, fullHeight) => {
+          const screenHeight = Math.max(1, vp.height);
+          const screens = Math.max(1, Math.ceil(fullHeight / screenHeight));
+          let quality = 70;
+          let height = fullHeight;
+          let shot = await take(vp, client, "jpeg", height, quality);
+          if (screenshot === "full" && shot.data.length > imageBytesEach && screens > 1) {
+            let keep = Math.min(screens - 1, Math.max(1, Math.floor(screens * imageBytesEach / shot.data.length)));
+            for (; ; ) {
+              height = Math.min(fullHeight, keep * screenHeight);
+              shot = await take(vp, client, "jpeg", height, quality);
+              if (shot.data.length <= imageBytesEach || keep === 1) break;
+              keep -= 1;
+            }
+          }
+          if (shot.data.length > imageBytesEach) {
+            quality = 40;
+            shot = await take(vp, client, "jpeg", height, quality);
+          }
+          const shown = screenshot === "full" ? Math.min(screens, Math.ceil(height / screenHeight)) : 1;
+          return {
+            mimeType: "image/jpeg",
+            base64: shot.data,
+            fit: { format: "jpeg", quality, screens: shown, of: screenshot === "full" ? screens : 1, overBudget: shot.data.length > imageBytesEach }
+          };
         };
         const expression = measureExpression(placeholders, probesFor(subjectComponent));
         let loggedThrough = 0;
@@ -2449,6 +2598,7 @@ var require_render_report = __commonJS({
       // Exported so a session-teardown hook, a CI step or a spec can reap without
       // starting a drive — the leak outlives the run that caused it.
       reapOrphanedRenderProcesses,
+      pageAnswers,
       routedPages: routedPages2,
       resolvePageRequest: resolvePageRequest2,
       reachableComponents,
@@ -2751,7 +2901,32 @@ function lookExpression(target) {
     const r = box.getBoundingClientRect();
     const visible = r.width > 0 && r.height > 0 && st.visibility !== 'hidden' && st.display !== 'none' && opacity > 0.05;
     const color = getComputedStyle(leaf).color;
-    return { text: label, visible, opacity: Math.round(opacity * 100) / 100, background: painted, backgroundName: name(painted), color, colorName: name(color) };
+    // P112-OWN019-LOOKBLIND \u2014 can a person read it: WCAG contrast of the ink (faded by every ancestor's opacity) against
+    // the ground composited from the text outwards (white under all of them, as a browser paints). null, never a guess,
+    // where a picture or gradient is behind the text or it casts a shadow. The same reading as render_report's
+    // low-contrast-text, so a page behind a sign-in can be checked from a drive.
+    let contrast = null;
+    const ink = rgba(getComputedStyle(leaf).webkitTextFillColor) || rgba(color);
+    if (ink && ink.a > 0 && (getComputedStyle(leaf).textShadow || 'none') === 'none') {
+      const over = (t, u) => ({ r: t.r * t.a + u.r * (1 - t.a), g: t.g * t.a + u.g * (1 - t.a), b: t.b * t.a + u.b * (1 - t.a), a: 1 });
+      const lum = (c) => { const f = (x) => { const v = x / 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b); };
+      const stack = [];
+      let picture = false;
+      for (let e = leaf; e; e = e.parentElement) {
+        const cs = getComputedStyle(e);
+        if (cs.backgroundImage && cs.backgroundImage !== 'none' && !/^url\\("data:image\\/svg/.test(cs.backgroundImage)) { picture = true; break; }
+        const bg = rgba(cs.backgroundColor);
+        if (bg && bg.a > 0) { stack.push(bg); if (bg.a >= 0.999) break; }
+      }
+      if (!picture) {
+        let ground = { r: 255, g: 255, b: 255, a: 1 };
+        while (stack.length) ground = over(stack.pop(), ground);
+        const fg = over({ r: ink.r, g: ink.g, b: ink.b, a: ink.a * opacity }, ground);
+        const x = lum(fg), y = lum(ground);
+        contrast = Math.round(((Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05)) * 100) / 100;
+      }
+    }
+    return { text: label, visible, opacity: Math.round(opacity * 100) / 100, background: painted, backgroundName: name(painted), color, colorName: name(color), contrast, readable: contrast === null ? null : contrast >= 3 };
   })()`;
 }
 function readExpression(r) {
@@ -2789,6 +2964,62 @@ function matches(value, expected) {
   }
   return JSON.stringify(value) === JSON.stringify(expected);
 }
+function watchShape(step, n) {
+  const w = step.watch && typeof step.watch === "object" ? step.watch : {};
+  if (w.look === void 0) throw new UsageError(`Step ${n}: watch takes { look: T } or { look: [T, T, \u2026] }.`);
+  const unknown = Object.keys(w).filter((k) => !["look", "for_ms", "expect"].includes(k));
+  if (unknown.length) throw new UsageError(`Step ${n}: watch does not take ${unknown.map((k) => JSON.stringify(k)).join(", ")} \u2014 it takes look, for_ms and expect.`);
+  if (step.expect !== void 0 && w.expect !== void 0) throw new UsageError(`Step ${n}: give watch one expect, beside it or inside it, not both.`);
+  const many = Array.isArray(w.look);
+  const targets = many ? w.look : [w.look];
+  if (targets.length === 0 || targets.length > 8) throw new UsageError(`Step ${n}: watch looks at 1 to 8 targets.`);
+  return {
+    many,
+    targets,
+    forMs: Math.min(1e4, Math.max(100, Number(step.for_ms ?? w.for_ms ?? 1500))),
+    expect: step.expect !== void 0 ? step.expect : w.expect,
+    expr: `Promise.all([${targets.map((t) => lookExpression(t)).join(", ")}])`
+  };
+}
+function checkStep(step, n, { outDir } = {}) {
+  const verb = verbOf(step, n);
+  const at = (fn) => {
+    try {
+      return fn();
+    } catch (error) {
+      if (!error.usage) throw new UsageError(`Step ${n}: ${error instanceof Error ? error.message : String(error)}`);
+      throw error.message.startsWith("Step ") ? error : new UsageError(`Step ${n}: ${error.message}`);
+    }
+  };
+  if (verb === "tap") at(() => finder(step.tap));
+  else if (verb === "type") {
+    if (typeof step.type !== "string") throw new UsageError(`Step ${n}: type takes a string.`);
+    if (step.into !== void 0) at(() => finder(step.into));
+  } else if (verb === "key") {
+    if (!KEYS[step.key]) throw new UsageError(`Step ${n}: key "${step.key}" is not one of ${Object.keys(KEYS).join(", ")}.`);
+  } else if (verb === "wait_for") at(() => waitExpression(step.wait_for));
+  else if (verb === "read") {
+    const r = step.read && typeof step.read === "object" ? step.read : null;
+    if (!r || !RUN_READS.some((k) => r[k] !== void 0)) at(() => readExpression(step.read));
+  } else if (verb === "navigate") {
+    if (typeof step.navigate !== "string") throw new UsageError(`Step ${n}: navigate takes a route string.`);
+  } else if (verb === "watch") watchShape(step, n);
+  else if (verb === "viewport") at(() => parseViewports(String(step.viewport)));
+  else if (verb === "screenshot") {
+    if (!outDir) throw new UsageError(`Step ${n}: screenshot needs --out-dir (render_report's out_dir rule).`);
+  } else if (verb === "seed_storage") {
+    const seed = step.seed_storage;
+    if (typeof seed === "string") {
+      if (typeof step.edit !== "string") throw new UsageError(`Step ${n}: seed_storage "${seed}" edits a saved value and needs edit: "js that changes v".`);
+    } else if (!seed || typeof seed !== "object" || Array.isArray(seed)) {
+      throw new UsageError(`Step ${n}: seed_storage takes { key: value } or a key with edit: "js that changes v".`);
+    }
+  } else if (verb === "stub_route") parseStub(step, n);
+  else if (verb === "reduced_motion") {
+    if (typeof step.reduced_motion !== "boolean") throw new UsageError(`Step ${n}: reduced_motion takes true or false.`);
+  }
+  return verb;
+}
 async function runSteps(page, steps, { outDir, stubs = routeStubs(page), network, beforeBoot = 0 }) {
   const rows = [];
   const pendingSeeds = [];
@@ -2914,17 +3145,7 @@ async function runSteps(page, steps, { outDir, stubs = routeStubs(page), network
         }
         row.url = await evaluate("location.pathname + location.hash");
       } else if (verb === "watch") {
-        const w = step.watch && typeof step.watch === "object" ? step.watch : {};
-        if (w.look === void 0) throw new UsageError(`Step ${i + 1}: watch takes { look: T } or { look: [T, T, \u2026] }.`);
-        const unknown = Object.keys(w).filter((k) => !["look", "for_ms", "expect"].includes(k));
-        if (unknown.length) throw new UsageError(`Step ${i + 1}: watch does not take ${unknown.map((k) => JSON.stringify(k)).join(", ")} \u2014 it takes look, for_ms and expect.`);
-        if (step.expect !== void 0 && w.expect !== void 0) throw new UsageError(`Step ${i + 1}: give watch one expect, beside it or inside it, not both.`);
-        const forMs = Math.min(1e4, Math.max(100, Number(step.for_ms ?? w.for_ms ?? 1500)));
-        const expect = step.expect !== void 0 ? step.expect : w.expect;
-        const many = Array.isArray(w.look);
-        const targets = many ? w.look : [w.look];
-        if (targets.length === 0 || targets.length > 8) throw new UsageError(`Step ${i + 1}: watch looks at 1 to 8 targets.`);
-        const expr = `Promise.all([${targets.map((t) => lookExpression(t)).join(", ")}])`;
+        const { many, targets, forMs, expect, expr } = watchShape(step, i + 1);
         const keyOf = (v) => v && typeof v === "object" ? JSON.stringify({ text: v.text, visible: v.visible, backgroundName: v.backgroundName, colorName: v.colorName, opacity: v.opacity === void 0 ? void 0 : Math.round(v.opacity * 10) / 10 }) : "null";
         const states = targets.map(() => []);
         const t0 = Date.now();
@@ -3007,8 +3228,8 @@ async function main() {
     return i === -1 ? void 0 : argv[i + 1];
   };
   const projectDir = argv.find((a, i) => !a.startsWith("--") && !VALUE_FLAGS.has(argv[i - 1]));
-  const usage = (message) => {
-    process.stdout.write(JSON.stringify({ error: { message, problems: [message], actionable: true } }));
+  const usage = (message, problems2 = [message]) => {
+    process.stdout.write(JSON.stringify({ error: { message, problems: problems2, actionable: true } }));
     process.exit(2);
   };
   if (!projectDir) usage("drive-steps.js <project-dir> --steps <json|@file> [--page p] [--viewport v] [--out-dir d]");
@@ -3018,12 +3239,22 @@ async function main() {
     if (!raw) throw new UsageError("--steps is required: a JSON array of steps.");
     steps = JSON.parse(raw.startsWith("@") ? fs.readFileSync(raw.slice(1), "utf8") : raw);
     if (!Array.isArray(steps) || steps.length === 0) throw new UsageError("--steps must be a non-empty JSON array.");
-    steps.forEach((s, i) => {
-      if (verbOf(s, i + 1) === "stub_route") parseStub(s, i + 1);
-    });
   } catch (error) {
     usage(error.message);
   }
+  const problems = [];
+  steps.forEach((step, i) => {
+    try {
+      checkStep(step, i + 1, { outDir: flag("--out-dir") });
+    } catch (error) {
+      if (!error.usage) throw error;
+      problems.push(error.message);
+    }
+  });
+  if (problems.length) {
+    problems.push("No step ran: every step is checked before the first one does.");
+    usage(problems.join(" "), problems);
+  }
   let viewport;
   try {
     [viewport] = parseViewports(flag("--viewport") || "desktop");
@@ -3075,9 +3306,9 @@ async function main() {
     process.stdout.write(JSON.stringify(result));
   } catch (error) {
     if (error.usage) usage(error.message);
-    const problems = error.problems || [error instanceof Error ? error.message : String(error)];
-    process.stdout.write(JSON.stringify({ error: { message: problems.join(" "), problems, actionable: Boolean(error.actionable) } }));
+    const problems2 = error.problems || [error instanceof Error ? error.message : String(error)];
+    process.stdout.write(JSON.stringify({ error: { message: problems2.join(" "), problems: problems2, actionable: Boolean(error.actionable) } }));
   }
 }
 if (require.main === module) main();
-module.exports = { runSteps, locateExpression, routeStubs, networkLog, parseStub, VERBS };
+module.exports = { runSteps, checkStep, locateExpression, routeStubs, networkLog, parseStub, VERBS };