@olomonhelpdesk2/helpdesk 0.1.18 → 0.1.19

package/helpdesk-capture.mjs

@@ -158,8 +158,14 @@ var CAPTURE_CONTRACT = {
   timezone: "UTC",
   /**
    * Injected before every shot. Necessary, not sufficient — see above.
+   *
+   * Every CSS animation ends at once, on its last frame, rather than being
+   * removed. An entrance starts its element at opacity 0 and keeps the last
+   * frame it animates to, and `animation: none` left that element at opacity
+   * 0, so a site's hero was blank in every frame. One that loops ends after a
+   * single instant pass, back at its element's own style.
    */
-  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}",
+  motionOff: "*,*::before,*::after{animation-duration:0s!important;animation-delay:0s!important;animation-iteration-count:1!important;transition:none!important;caret-color:transparent!important}",
   /**
    * What an app uses to leave its own floating widgets out of the pictures.
    *
@@ -221,7 +227,13 @@ function subjectOf(path5) {
   const segments = path5.split("/").filter(Boolean).filter((segment) => !/^(api|v\d+)$/.test(segment));
   while (segments.length > 1 && looksLikeAnId(segments[segments.length - 1])) segments.pop();
   const last = segments[segments.length - 1] ?? "record";
-  return last.replace(/[-_]/g, " ").replace(/s$/, "");
+  return singular(last.replace(/[-_]/g, " "));
+}
+function singular(word) {
+  if (/ies$/.test(word)) return word.replace(/ies$/, "y");
+  if (/(ss|sh|ch|x|z|us)es$/.test(word)) return word.replace(/es$/, "");
+  if (/(ss|us)$/.test(word)) return word;
+  return word.replace(/s$/, "");
 }
 function looksLikeAnId(segment) {
   return /^\[{1,2}[^\]]+\]{1,2}$/.test(segment) || /^\d+$/.test(segment) || /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(segment) || // `inv_123`, `cus_9f2a`: a prefix, a separator, and something with a digit
@@ -348,6 +360,35 @@ function firstSentence(text2) {
   const sentence = text2.trim().split(/(?<=[.!?])\s|\n/)[0] ?? text2;
   return sentence.length > 160 ? `${sentence.slice(0, 157)}\u2026` : sentence;
 }
+var OPAQUE_SCRIPT_ERROR = /^script error\.?$/i;
+function frameUrls(stack) {
+  return stack.split("\n").filter((line) => /^\s*at\s/.test(line)).flatMap((line) => {
+    const url = /\bhttps?:\/\/[^\s()]+?(?=:\d+(?::\d+)?\)?$)/.exec(line.trim())?.[0];
+    return url ? [url] : [];
+  });
+}
+function siteOf(host) {
+  return /^[\d.]+$|^\[|^[^.]+$/.test(host) ? host : host.split(".").slice(-2).join(".");
+}
+function thrownElsewhere(error, pageUrl) {
+  let page;
+  try {
+    page = new URL(pageUrl);
+  } catch {
+    return void 0;
+  }
+  const urls = frameUrls(error.stack ?? "");
+  if (urls.length === 0) return OPAQUE_SCRIPT_ERROR.test(error.message.trim()) ? "a script from another site" : void 0;
+  const hosts = urls.flatMap((url) => {
+    try {
+      return [new URL(url).hostname];
+    } catch {
+      return [];
+    }
+  });
+  if (hosts.length === 0 || hosts.some((host) => siteOf(host) === siteOf(page.hostname))) return void 0;
+  return hosts[0];
+}
 function surveyLine(outcomes) {
   const count = (result) => outcomes.filter((outcome) => outcome.result === result).length;
   const crashed = count("crashed");
@@ -487,6 +528,15 @@ function runIdentityFromEnv(env) {
 }
 
 // core/capture/run-verdict.ts
+function clipSuccessRate(clips) {
+  const played = clips.recorded + clips.unchanged;
+  const tried = played + clips.refused + clips.failed;
+  return tried ? { played, tried, percent: Math.round(played / tried * 100) } : null;
+}
+function clipCounts(clips) {
+  const rate = clipSuccessRate(clips);
+  return `${clips.recorded} recorded, ${clips.unchanged} unchanged, ${clips.deferred} deferred, ${clips.refused} refused, ${clips.failed} failed${rate ? `: ${rate.played} of ${rate.tried} play (${rate.percent}%)` : ""}`;
+}
 function runCounts(run2) {
   return `${run2.captured} photographed, ${run2.unchanged} unchanged, ${run2.skipped} skipped, ${run2.refused} refused, ${run2.failed} failed`;
 }
@@ -859,6 +909,70 @@ function paeth(a, b, c) {
   const pc = Math.abs(p - c);
   return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
 }
+function encodePng(image) {
+  const stride = image.width * 4;
+  const raw = Buffer.alloc(image.height * (stride + 1));
+  const previous = Buffer.alloc(stride);
+  const tries = [0, 1, 2, 3, 4].map(() => Buffer.alloc(stride));
+  for (let y = 0; y < image.height; y += 1) {
+    const line = image.pixels.subarray(y * stride, (y + 1) * stride);
+    let best = 0;
+    let bestCost = Number.POSITIVE_INFINITY;
+    for (let filter = 0; filter <= 4; filter += 1) {
+      const out = tries[filter];
+      let cost = 0;
+      for (let index = 0; index < stride; index += 1) {
+        const x = line[index];
+        const a = index >= 4 ? line[index - 4] : 0;
+        const b = previous[index];
+        const c = index >= 4 ? previous[index - 4] : 0;
+        const value = filter === 0 ? x : filter === 1 ? x - a & 255 : filter === 2 ? x - b & 255 : filter === 3 ? x - (a + b >> 1) & 255 : x - paeth(a, b, c) & 255;
+        out[index] = value;
+        cost += value < 128 ? value : 256 - value;
+      }
+      if (cost < bestCost) {
+        bestCost = cost;
+        best = filter;
+      }
+    }
+    raw[y * (stride + 1)] = best;
+    tries[best].copy(raw, y * (stride + 1) + 1);
+    line.copy(previous);
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(image.width, 0);
+  header.writeUInt32BE(image.height, 4);
+  header.writeUInt8(8, 8);
+  header.writeUInt8(6, 9);
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(raw, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0))
+  ]);
+}
+function chunk(type, body) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(body.length, 0);
+  head.write(type, 4, "ascii");
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+  return Buffer.concat([head, body, tail]);
+}
+var crcTable;
+function crc32(bytes) {
+  if (!crcTable) {
+    crcTable = new Uint32Array(256);
+    for (let index = 0; index < 256; index += 1) {
+      let value = index;
+      for (let bit = 0; bit < 8; bit += 1) value = value & 1 ? 3988292384 ^ value >>> 1 : value >>> 1;
+      crcTable[index] = value >>> 0;
+    }
+  }
+  let crc = 4294967295;
+  for (const byte of bytes) crc = crcTable[(crc ^ byte) & 255] ^ crc >>> 8;
+  return (crc ^ 4294967295) >>> 0;
+}
 function coveredFraction(image) {
   const total = image.width * image.height;
   if (total === 0) return 0;
@@ -913,8 +1027,14 @@ async function takeInventory(page, regions) {
       const rendered = (element) => {
         const style = styleOf(element);
         if (style.visibility === "hidden" || style.display === "none") return false;
+        const clip = style.clip.replace(/\s|px/g, "");
+        if (clip === "rect(0,0,0,0)" || clip === "rect(0000)") return false;
+        if (/\binset\(\s*50%/.test(style.clipPath)) return false;
+        const view = element.ownerDocument?.defaultView ?? window;
         for (const box of Array.from(element.getClientRects())) {
-          if (box.width > 0 && box.height > 0) return true;
+          if (box.width <= 1 || box.height <= 1) continue;
+          if (box.bottom + view.scrollY <= 0 || box.right + view.scrollX <= 0) continue;
+          return true;
         }
         return false;
       };
@@ -1180,6 +1300,61 @@ async function readPageLayout(page, cover = []) {
           }
           return contentOf(element) || clean(element.getAttribute("title"));
         };
+        const readable = (node) => {
+          const box = node.getBoundingClientRect();
+          return !unseen(node) && box.width >= 4 && box.height >= 4;
+        };
+        const labelText = (label) => {
+          let text2 = label.innerText ?? "";
+          for (const inner of Array.from(label.querySelectorAll("select, textarea, button, [contenteditable]"))) {
+            const own = inner.innerText ?? "";
+            if (own) text2 = text2.replace(own, " ");
+          }
+          return clean(text2);
+        };
+        const labelsOf = (element, role) => {
+          const found = [];
+          const add = (text2) => {
+            if (text2 && !found.includes(text2)) found.push(text2);
+          };
+          const tag = element.tagName.toLowerCase();
+          const native = tag === "input" || tag === "textarea" || tag === "select";
+          for (const id of clean(element.getAttribute("aria-labelledby")).split(" ").filter(Boolean)) {
+            const target = document.getElementById(id);
+            if (target && readable(target)) add(labelText(target));
+          }
+          if (native) {
+            const field = element;
+            const type = clean(field.getAttribute("type")).toLowerCase();
+            if (type === "submit" || type === "reset" || type === "button") add(clean(field.value));
+            for (const label of Array.from(field.labels ?? [])) if (readable(label)) add(labelText(label));
+            if (tag !== "select" && field.value === "") add(clean(field.getAttribute("placeholder")));
+          } else if (role === "textbox" || role === "searchbox") {
+            if (!clean(element.innerText)) add(clean(element.getAttribute("aria-placeholder")));
+          } else {
+            add(clean(element.innerText));
+          }
+          return found.map((text2) => text2.slice(0, 200)).slice(0, 4);
+        };
+        const fieldOf = (element, role) => {
+          if (role !== "textbox" && role !== "searchbox" && role !== "spinbutton" && role !== "combobox") return void 0;
+          const tag = element.tagName.toLowerCase();
+          if (tag !== "input" && tag !== "textarea") {
+            if (role !== "textbox") return void 0;
+            return { kind: "textarea", empty: !clean(element.innerText) };
+          }
+          const field = element;
+          const attribute = (name) => clean(field.getAttribute(name)).toLowerCase();
+          const maxLength = field.maxLength > 0 ? field.maxLength : void 0;
+          return {
+            kind: tag === "textarea" ? "textarea" : attribute("type") || "text",
+            empty: field.value === "",
+            ...attribute("autocomplete") ? { autocomplete: attribute("autocomplete").slice(0, 60) } : {},
+            ...attribute("inputmode") ? { inputmode: attribute("inputmode").slice(0, 20) } : {},
+            ...field.required || element.getAttribute("aria-required") === "true" ? { required: true } : {},
+            ...maxLength ? { maxLength } : {}
+          };
+        };
         const stateOf = (element, role) => {
           const state = {};
           const aria = (name) => element.getAttribute(`aria-${name}`);
@@ -1289,7 +1464,8 @@ async function readPageLayout(page, cover = []) {
           if (box.width < 2 || box.height < 2) continue;
           if (CONTROLS.includes(role)) {
             const href = role === "link" ? element.href || element.getAttribute("href") : null;
-            controls.push({ role, name: nameOf(element), box, state: stateOf(element, role), ...href ? { href } : {} });
+            const field = fieldOf(element, role);
+            controls.push({ role, name: nameOf(element), labels: labelsOf(element, role), box, state: stateOf(element, role), ...href ? { href } : {}, ...field ? { field } : {} });
           } else if (LANDMARKS.includes(role)) {
             regions.push({ kind: role === "dialog" || role === "alertdialog" ? "dialog" : "landmark", role, label: labelOf(element), box });
           } else if (role === "heading") {
@@ -1458,7 +1634,27 @@ function ownPath(href, origin) {
     return void 0;
   }
 }
-function buildLayoutManifest(layout, frame) {
+var MAX_LABELS = 4;
+function readLabels(value) {
+  if (!Array.isArray(value)) return void 0;
+  return [...new Set(value.map(textOf).filter(Boolean))].slice(0, MAX_LABELS);
+}
+function readField(value) {
+  const given = recordOf(value);
+  const kind = typeof given["kind"] === "string" ? given["kind"].toLowerCase() : "";
+  if (!/^[a-z-]{1,30}$/.test(kind) || typeof given["empty"] !== "boolean") return void 0;
+  const word = (key, limit) => typeof given[key] === "string" && given[key] ? { [key]: given[key].toLowerCase().slice(0, limit) } : {};
+  const maxLength = given["maxLength"];
+  return {
+    kind,
+    empty: given["empty"],
+    ...word("autocomplete", 60),
+    ...word("inputmode", 20),
+    ...given["required"] === true ? { required: true } : {},
+    ...typeof maxLength === "number" && Number.isInteger(maxLength) && maxLength > 0 ? { maxLength } : {}
+  };
+}
+function buildLayoutManifest(layout, frame, options = {}) {
   const { viewport, scale } = layout;
   const regions = [];
   for (const raw of layout.regions.slice(0, MAX_REGIONS)) {
@@ -1475,7 +1671,18 @@ function buildLayoutManifest(layout, frame) {
     if (!where) continue;
     const href = raw.role === "link" ? ownPath(raw.href, frame.origin) : void 0;
     const state = readState(raw.state);
-    controls.push({ role: raw.role, name: textOf(raw.name), box: where.box, clipped: where.clipped, ...state ? { state } : {}, ...href ? { href } : {} });
+    const labels = options.live ? readLabels(raw.labels) : void 0;
+    const field = options.live ? readField(raw.field) : void 0;
+    controls.push({
+      role: raw.role,
+      name: textOf(raw.name),
+      box: where.box,
+      clipped: where.clipped,
+      ...state ? { state } : {},
+      ...href ? { href } : {},
+      ...labels ? { labels } : {},
+      ...field ? { field } : {}
+    });
   }
   return {
     schema: LAYOUT_MANIFEST_SCHEMA,
@@ -1521,7 +1728,9 @@ function assemble(regions, controls) {
         ...region ? { region } : {},
         ...control.state ? { state: control.state } : {},
         ...control.href ? { href: control.href } : {},
-        ...control.clipped ? { clipped: true } : {}
+        ...control.clipped ? { clipped: true } : {},
+        ...control.labels ? { labels: control.labels } : {},
+        ...control.field ? { field: control.field } : {}
       };
     })
   };
@@ -1540,7 +1749,7 @@ var CLIP_MAX_GIF_BYTES = 8 * 1024 * 1024;
 var CLIP_GIF_WIDTH = 960;
 var CLIP_ACTIONS = ["click", "fill", "select", "check", "auto"];
 function actionForRole(role, value) {
-  if (role === "textbox" || role === "searchbox") return "fill";
+  if (role === "textbox" || role === "searchbox" || role === "spinbutton") return "fill";
   if ((role === "combobox" || role === "listbox") && value) return "select";
   if (role === "checkbox" || role === "radio" || role === "switch") return "check";
   return "click";
@@ -1667,7 +1876,16 @@ function readClipScripts(raw, limit = MAX_SEEDED_SCRIPTS) {
   return { scripts, refused };
 }
 function comparable(text2) {
-  return cleanText(text2).toLowerCase().replace(/(…|\.\.\.)$/, "").trim();
+  return cleanText(text2).toLowerCase().replace(/\s*\*$/, "").replace(/(…|\.\.\.)$/, "").trim();
+}
+function wordsFor(control, step) {
+  return !step.control.role && control.labels ? control.labels : [control.name];
+}
+function emptyFieldsBeside(manifest, control) {
+  const region = control.region ? /* @__PURE__ */ new Set([control.region]) : void 0;
+  const empty = manifest.controls.filter((other) => other !== control && other.field?.empty && (!region || within(manifest, other, region)));
+  const required = empty.filter((other) => other.field?.required);
+  return (required.length ? required : empty).map((other) => other.labels?.[0] ?? other.name).filter(Boolean).slice(0, 4);
 }
 var CHROME_ROLES = ["navigation", "complementary", "banner", "contentinfo"];
 var IN_CHROME = /\b(sidebar|side bar|menu|navigation|nav bar|top bar|header)\b/i;
@@ -1700,8 +1918,8 @@ function resolveStep(manifest, step, options = {}) {
   const role = step.control.role;
   const what = role ?? "control";
   const candidates = manifest.controls.filter((control) => !role || control.role === role);
-  let matches = candidates.filter((control) => comparable(control.name) === name);
-  if (!role && !matches.length) matches = candidates.filter((control) => namesControl(control.name, step.control.name));
+  let matches = candidates.filter((control) => wordsFor(control, step).some((word) => comparable(word) === name));
+  if (!role && !matches.length) matches = candidates.filter((control) => wordsFor(control, step).some((word) => namesControl(word, step.control.name)));
   const scope = step.control.scope;
   if (scope && matches.length > 1) {
     const regions = new Set(manifest.regions.filter((region) => region.id === scope || comparable(region.label) === comparable(scope)).map((region) => region.id));
@@ -1719,7 +1937,10 @@ function resolveStep(manifest, step, options = {}) {
   if (matches.length > 1) {
     return { ok: false, kind: "ambiguous", because: `${matches.length} of ${what} "${step.control.name}" on ${where}${scope ? ` in ${scope}` : ""}, so the step does not say which` };
   }
-  if (matches[0].state?.disabled) return { ok: false, kind: "disabled", because: `${what} "${step.control.name}" on ${where} is disabled` };
+  if (matches[0].state?.disabled) {
+    const waiting = emptyFieldsBeside(manifest, matches[0]);
+    return { ok: false, kind: "disabled", because: `${what} "${step.control.name}" on ${where} is disabled${waiting.length ? `, with nothing yet in ${waiting.join(", ")} beside it` : ""}` };
+  }
   return { ok: true, control: matches[0] };
 }
 function onScreen(route, location2) {
@@ -1966,7 +2187,8 @@ function readRenderedFactRecords(html, options = {}) {
       })
     );
   };
-  for (const element of elements(visibleMarkup(html))) {
+  const markup = visibleMarkup(html);
+  for (const element of elements(markup)) {
     const { tag, attributes, inner, landmark } = element;
     const role = attributes["role"]?.toLowerCase() ?? "";
     const label = accessibleName(element);
@@ -1987,11 +2209,12 @@ function readRenderedFactRecords(html, options = {}) {
       continue;
     }
     if (tag === "input" || tag === "textarea" || tag === "select") {
-      const field = fieldFrom(element, html);
+      const field = fieldFrom(element, html, markup);
       if (field) {
         add("field", field.label, landmark, {
           fieldKind: field.kind,
           ...field.choices ? { choices: field.choices } : {},
+          ...field.placeholder ? { placeholder: field.placeholder } : {},
           ...controlState(element)
         });
       }
@@ -2040,6 +2263,7 @@ function toScreenFacts(facts, from) {
       case "field": {
         const field = { label: entry.value, kind: entry.fieldKind ?? "text" };
         if (entry.choices?.length) field.choices = [...entry.choices];
+        if (entry.placeholder) field.placeholder = entry.placeholder;
         fields.push(field);
         break;
       }
@@ -2225,20 +2449,32 @@ function submitLike(element) {
   const type = element.attributes["type"]?.toLowerCase();
   return type === "submit" || type === "button" || type === "reset";
 }
-function fieldFrom(element, body) {
+function fieldFrom(element, body, markup) {
   const { tag, attributes } = element;
   const type = attributes["type"]?.toLowerCase() ?? "text";
   if (tag === "input" && (type === "hidden" || submitLike(element))) return void 0;
   const kind = tag === "input" ? type : tag;
-  const label = attributes["aria-label"]?.trim() || attributes["placeholder"]?.trim() || labelFor(body, attributes["id"]) || humanise(attributes["name"] ?? "");
+  const label = attributes["aria-label"]?.trim() || labelAround(markup, element.at) || attributes["placeholder"]?.trim() || labelFor(body, attributes["id"]) || humanise(attributes["name"] ?? "");
   if (!label) return void 0;
   const field = { label: trim(label.replace(/\s+/g, " "), LIMITS.label), kind };
+  const placeholder = attributes["placeholder"]?.trim().replace(/\s+/g, " ");
+  if (placeholder && placeholder !== label.trim()) field.placeholder = trim(placeholder, LIMITS.label);
   if (tag === "select") {
     const choices = [...element.inner.matchAll(/<option\b[^>]*>([\s\S]*?)<\/option>/gi)].map((match) => text(match[1] ?? "")).filter(Boolean).slice(0, LIMITS.choices);
     if (choices.length) field.choices = choices;
   }
   return field;
 }
+function labelAround(markup, at) {
+  const open = markup.lastIndexOf("<label", at);
+  if (open < 0 || !/^<label[\s>]/i.test(markup.slice(open, open + 7))) return "";
+  const start = markup.indexOf(">", open) + 1;
+  const close = markup.indexOf("</label>", start);
+  if (start <= 0 || close < at) return "";
+  const inner = markup.slice(start, close).replace(/<(select|textarea|button)\b[\s\S]*?<\/\1>/gi, " ").replace(/<input\b[^>]*>/gi, " ").trim();
+  const first = /^(?:<(\w+)\b[^>]*>([\s\S]*?)<\/\1>|([^<]+))/.exec(inner);
+  return text(first?.[2] ?? first?.[3] ?? "");
+}
 function labelFor(body, id) {
   if (!id) return "";
   const match = new RegExp(
@@ -3091,6 +3327,8 @@ async function playwrightBrowser(options = {}) {
     // on who took it.
     timezoneId: CAPTURE_CONTRACT.timezone,
     locale: CAPTURE_CONTRACT.locale,
+    // A page that offers a still version of itself to somebody who asked for less motion shows that one.
+    reducedMotion: "reduce",
     /**
      * A session, when one is supplied — and only ever from a file on the
      * machine running this.
@@ -3112,7 +3350,11 @@ async function playwrightBrowser(options = {}) {
      */
     ...options.sessionPath ? { storageState: options.sessionPath } : { storageState: void 0 }
   };
+  const elsewhere = /* @__PURE__ */ new Map();
   return {
+    thrownElsewhere() {
+      return [...elsewhere.values()].map((held) => ({ by: held.by, message: held.message, screens: [...held.screens] }));
+    },
     async page(wanted) {
       const phone = phoneViewport(wanted?.width);
       const context = await browser.newContext(
@@ -3127,7 +3369,17 @@ async function playwrightBrowser(options = {}) {
       const consoleErrors = [];
       const failedRequests = [];
       let status;
-      page.on("pageerror", (error) => errors.push(error.message));
+      page.on("pageerror", (error) => {
+        const by = thrownElsewhere(error, page.url());
+        if (!by) {
+          errors.push(error.message);
+          return;
+        }
+        const key = `${by}\0${error.message}`;
+        const held = elsewhere.get(key) ?? { by, message: error.message, screens: /* @__PURE__ */ new Set() };
+        held.screens.add(pathOf(page.url()));
+        elsewhere.set(key, held);
+      });
       page.on("console", (message) => {
         if (message.type() === "error") consoleErrors.push(message.text());
       });
@@ -3146,6 +3398,16 @@ async function playwrightBrowser(options = {}) {
           await page.addStyleTag({ content: CAPTURE_CONTRACT.hideOff }).catch(() => void 0);
           await page.evaluate((name) => document.documentElement.setAttribute(name, ""), CAPTURE_CONTRACT.marker).catch(() => void 0);
           await page.evaluate(() => document.fonts?.ready).catch(() => void 0);
+          await page.evaluate(() => {
+            for (const animation of document.getAnimations()) {
+              const end = animation.effect?.getComputedTiming().endTime;
+              if (typeof end !== "number" || !Number.isFinite(end)) continue;
+              try {
+                animation.finish();
+              } catch {
+              }
+            }
+          }).catch(() => void 0);
         },
         async text() {
           return page.locator("body").innerText().catch(() => "");
@@ -3244,6 +3506,16 @@ async function playwrightBrowser(options = {}) {
             ...masks.length > 0 ? { mask: masks, maskColor: PUBLICATION_REDACTION_CSS } : {}
           });
         },
+        async frame(cover) {
+          for (let attempt = 1; ; attempt += 1) {
+            const before = await coversOf(page, cover ?? []).catch(() => void 0);
+            const bytes = before ? await page.screenshot({ type: "png", fullPage: false }).catch(() => void 0) : void 0;
+            const after = bytes ? await coversOf(page, cover ?? []).catch(() => void 0) : void 0;
+            if (before && bytes && after && sameCovers(before, after)) return paintCovers(bytes, after);
+            if (attempt >= 4) throw new Error("the page kept changing while its frame was taken, so no frame of it could be covered");
+            await page.waitForLoadState("load", { timeout: 1e4 }).catch(() => void 0);
+          }
+        },
         async close() {
           await context.close();
         }
@@ -3285,6 +3557,43 @@ function coverageOf(image) {
     return 0;
   }
 }
+async function coversOf(page, selectors) {
+  const found = await page.evaluate((wanted) => {
+    const boxes = [];
+    for (const selector of wanted) {
+      let elements2;
+      try {
+        elements2 = Array.from(document.querySelectorAll(selector));
+      } catch {
+        return { unreadable: selector };
+      }
+      for (const element of elements2) {
+        for (const box of Array.from(element.getClientRects())) boxes.push({ x: box.x, y: box.y, width: box.width, height: box.height });
+      }
+    }
+    return { document: performance.timeOrigin, scale: window.devicePixelRatio, boxes };
+  }, [...selectors]);
+  if ("unreadable" in found) throw new Error(`the cover ${found.unreadable} is not a selector this page can find`);
+  return found;
+}
+function sameCovers(before, after) {
+  return before.document === after.document && before.scale === after.scale && JSON.stringify(before.boxes) === JSON.stringify(after.boxes);
+}
+function paintCovers(bytes, covers) {
+  if (covers.boxes.length === 0) return bytes;
+  const image = decodePng(Buffer.from(bytes));
+  const { r, g, b } = PUBLICATION_REDACTION;
+  for (const box of covers.boxes) {
+    const left = Math.max(0, Math.floor(box.x * covers.scale));
+    const top = Math.max(0, Math.floor(box.y * covers.scale));
+    const right = Math.min(image.width, Math.ceil((box.x + box.width) * covers.scale));
+    const bottom = Math.min(image.height, Math.ceil((box.y + box.height) * covers.scale));
+    for (let y = top; y < bottom; y += 1) {
+      for (let x = left; x < right; x += 1) image.pixels.set([r, g, b, 255], (y * image.width + x) * 4);
+    }
+  }
+  return new Uint8Array(encodePng(image));
+}
 var PUBLICATION_REDACTION_CSS = `#${[PUBLICATION_REDACTION.r, PUBLICATION_REDACTION.g, PUBLICATION_REDACTION.b].map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
 async function readOpaqueSurfaces(page, regions) {
   return page.evaluate(
@@ -3463,6 +3772,34 @@ import { spawn } from "node:child_process";
 import { createHash as createHash3 } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path2 from "node:path";
+
+// core/capture/demo-fill.ts
+var DEMO_KEY = "demo-key-not-real";
+var UNTYPED = /* @__PURE__ */ new Set(["date", "datetime-local", "month", "week", "time", "color", "range", "file", "checkbox", "radio", "hidden"]);
+function demoValueForField(control) {
+  const field = control.field;
+  const kind = field?.kind ?? (control.role === "spinbutton" ? "number" : control.role === "searchbox" ? "search" : "text");
+  const autocomplete = field?.autocomplete ?? "";
+  const inputmode = field?.inputmode ?? "";
+  const words = [...control.labels ?? [], control.name].join(" ").toLowerCase();
+  const value = (() => {
+    if (UNTYPED.has(kind)) return void 0;
+    if (kind === "password" || autocomplete.includes("password") || /\b(key|token|secret|password|passphrase)\b/.test(words)) return DEMO_KEY;
+    if (kind === "email" || autocomplete.includes("email") || inputmode === "email" || /\be-?mail\b/.test(words) || /[^\s@]+@[^\s@]+\.[a-z]{2,}/.test(words)) return "demo@example.com";
+    if (/\bsub-?domain\b|\bslug\b/.test(words)) return "demo";
+    if (kind === "url" || autocomplete === "url" || inputmode === "url" || /\b(url|website|web address|domain|link)\b/.test(words) || /\bhttps?:\/\/|\bwww\./.test(words)) return "https://demo.example.com";
+    if (kind === "tel" || autocomplete.startsWith("tel") || inputmode === "tel" || /\bphone\b/.test(words)) return "555-0100";
+    if (kind === "number" || inputmode === "numeric" || inputmode === "decimal") return "3";
+    if (/\bjson\b/.test(words)) return '{"demo": true}';
+    if (autocomplete === "username" || /\b(user ?name|login|handle)\b/.test(words)) return "demo";
+    if (kind === "search") return "demo";
+    if (kind === "textarea") return "Demo text, typed for this recording.";
+    return "Demo";
+  })();
+  return value && field?.maxLength ? value.slice(0, field.maxLength) : value;
+}
+
+// adapters/capture-clips.ts
 var FRAME_MS = 1e3 / CLIP_FPS;
 var OPENING_MS = 700;
 var MOVE_FRAMES = 6;
@@ -3476,6 +3813,7 @@ var CLOSING_MS = 1200;
 var SCROLL_TO = 0.45;
 var WHOLE_SHIFT = 1e5;
 var START = { x: Math.round(CLIP_VIEWPORT.width / 2), y: Math.round(CLIP_VIEWPORT.height * 0.66) };
+var CLIP_DEADLINE_MS = 12e4;
 function wholePage(raw) {
   const down = (item) => ({ ...item, box: { ...item.box, y: item.box.y + WHOLE_SHIFT } });
   return { ...raw, viewport: { width: raw.viewport.width, height: 2 * WHOLE_SHIFT }, regions: raw.regions.map(down), controls: raw.controls.map(down) };
@@ -3483,14 +3821,40 @@ function wholePage(raw) {
 function chunksOf(text2, size) {
   return Array.from({ length: Math.ceil(text2.length / size) }, (_, index) => text2.slice(index * size, (index + 1) * size));
 }
+var CLIP_LATE = "so its page was closed and the run went on";
 async function recordClip(options, script, touched) {
+  const limit = options.deadlineMs ?? CLIP_DEADLINE_MS;
+  const late = { ok: false, status: "failed", because: `it did not finish within ${limit / 1e3} s, ${CLIP_LATE}` };
+  let page;
+  let expired = false;
+  let deadline;
+  const lapsed = new Promise((resolve) => {
+    deadline = setTimeout(() => {
+      expired = true;
+      void page?.close().catch(() => void 0);
+      resolve("late");
+    }, limit);
+  });
+  const opening = options.browser.page({ variant: "clip" }).catch(() => void 0);
+  void opening.then((opened) => expired ? opened?.close().catch(() => void 0) : void 0);
+  try {
+    const opened = await Promise.race([opening, lapsed]);
+    if (opened === "late") return late;
+    if (!opened) return { ok: false, status: "failed", because: "the browser would not open a page to record in" };
+    page = opened;
+    const result = await Promise.race([recordOn(options, script, touched, opened), lapsed]);
+    return result === "late" || expired ? late : result;
+  } finally {
+    clearTimeout(deadline);
+    if (page) await Promise.race([page.close().catch(() => void 0), new Promise((resolve) => setTimeout(resolve, 5e3))]);
+  }
+}
+async function recordOn(options, script, touched, page) {
   const dir = path2.join(options.workDir, script.id);
   const frames = [];
   const checked = /* @__PURE__ */ new Set();
   const fail = (because) => ({ ok: false, status: "failed", because });
   const refuse = (because) => ({ ok: false, status: "refused", because });
-  const page = await options.browser.page({ variant: "clip" }).catch(() => void 0);
-  if (!page) return fail("the browser would not open a page to record in");
   try {
     await rm(dir, { recursive: true, force: true });
     await mkdir(dir, { recursive: true });
@@ -3530,13 +3894,14 @@ async function recordClip(options, script, touched) {
       at += ms;
       return file;
     };
-    const shoot = async (ms) => keep(await page.screenshot(cover), ms);
+    const picture = (covered) => page.frame ? page.frame(covered) : page.screenshot(covered);
+    const shoot = async (ms) => keep(await picture(cover), ms);
     const hold = (ms) => {
       frames[frames.length - 1].ms += ms;
       at += ms;
     };
     const film = async () => {
-      const next = await page.screenshot(cover);
+      const next = await picture(cover);
       if (sameBytes(next, last)) {
         hold(FRAME_MS);
         return false;
@@ -3547,19 +3912,23 @@ async function recordClip(options, script, touched) {
     const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     let redirected;
     const isOn = (route, where) => onScreen(route, where) || redirected?.route === route && where.split("?")[0] === redirected.path;
-    const manifestOf = (raw, step, where) => buildLayoutManifest(raw, {
-      shotId: script.id,
-      route: step.route,
-      path: where.split("?")[0],
-      variant: "desktop",
-      image: { width: raw.viewport.width, height: raw.viewport.height },
-      origin: new URL(options.baseUrl).origin
-    });
+    const manifestOf = (raw, step, where) => buildLayoutManifest(
+      raw,
+      {
+        shotId: script.id,
+        route: step.route,
+        path: where.split("?")[0],
+        variant: "desktop",
+        image: { width: raw.viewport.width, height: raw.viewport.height },
+        origin: new URL(options.baseUrl).origin
+      },
+      { live: true }
+    );
     const steady = async () => {
-      let previous = await page.screenshot(cover);
+      let previous = await picture(cover);
       for (let waited = 0; waited < SETTLE_MS; waited += FRAME_MS) {
         await pause(FRAME_MS);
-        const next = await page.screenshot(cover);
+        const next = await picture(cover);
         if (sameBytes(next, previous)) return;
         previous = next;
       }
@@ -3620,11 +3989,26 @@ async function recordClip(options, script, touched) {
       () => null,
       (error) => error instanceof Error ? error.message : String(error)
     );
+    const landed = async (typedInto, step, where) => {
+      const at2 = centreOf(typedInto.box);
+      const field = manifestOf(await layout(cover), step, where).controls.find(
+        (control) => control.field && at2.x >= control.box.x && at2.x <= control.box.x + control.box.width && at2.y >= control.box.y && at2.y <= control.box.y + control.box.height
+      );
+      return field?.name !== typedInto.name || !field.field?.empty;
+    };
+    const here = async (step, filming) => {
+      if (step.control.role || step.action !== "auto" || step.follows) return void 0;
+      const where = await location2();
+      if (isOn(step.route, where)) return void 0;
+      const resolution = await find(step, where, filming);
+      return resolution.ok ? { where, resolution } : void 0;
+    };
     const performedOn = (step, where) => isOn(step.route, where) ? step.route : [...script.before ?? [], ...script.steps].map((each) => each.route).find((route) => isOn(route, where)) ?? where.split("?")[0];
     const lead = async (step) => {
-      const where = step.follows ? await settled() : await reach(step.route, step.opens);
-      if (!step.follows && !isOn(step.route, where)) return `the browser is on ${where}, not ${step.route}`;
-      let resolution = await find(step, where, false);
+      const shown = await here(step, false);
+      const where = shown?.where ?? (step.follows ? await settled() : await reach(step.route, step.opens));
+      if (!shown && !step.follows && !isOn(step.route, where)) return `the browser is on ${where}, not ${step.route}`;
+      let resolution = shown?.resolution ?? await find(step, where, false);
       for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await pause(FRAME_MS);
         resolution = await find(step, where, false);
@@ -3633,12 +4017,13 @@ async function recordClip(options, script, touched) {
       lastRegion = resolution.control.region;
       const target = centreOf(resolution.control.box);
       const action = step.action === "auto" ? actionForRole(resolution.control.role, step.value) : step.action;
-      const typed = step.value ?? step.demo;
+      const typed = step.value ?? step.demo ?? demoValueForField(resolution.control);
       if (action === "fill") {
         if (!typed) return `it types into ${resolution.control.name}, and says nothing to type`;
         const unfocused = await focus(target);
         if (unfocused) return unfocused;
         await type(typed);
+        if (!await landed(resolution.control, step, where)) return `what was typed into ${resolution.control.name} did not land, and the field still holds nothing`;
       } else if (action === "select") {
         await pointer({ kind: "select", at: target, value: step.value ?? "" });
       } else {
@@ -3661,8 +4046,9 @@ async function recordClip(options, script, touched) {
       if (problem) return fail(`before the recording, step ${index + 1}: ${problem}`);
     }
     const first = script.steps[0];
-    const starting = !script.before?.length ? opened : first.follows ? await settled() : await reach(first.route, first.opens);
-    if (!first.follows && !isOn(first.route, starting)) return fail(`once the steps before it were done, the browser is on ${starting}, not ${first.route}`);
+    const already = script.before?.length ? await here(first, false) : void 0;
+    const starting = !script.before?.length ? opened : already?.where ?? (first.follows ? await settled() : await reach(first.route, first.opens));
+    if (!already && !first.follows && !isOn(first.route, starting)) return fail(`once the steps before it were done, the browser is on ${starting}, not ${first.route}`);
     const before = await judge(starting);
     if (before) return before;
     let poster;
@@ -3685,11 +4071,12 @@ async function recordClip(options, script, touched) {
     await cursor(resting);
     checked.add(await shoot(OPENING_MS));
     for (const [index, step] of script.steps.entries()) {
-      const where = await arrive(step.route, step.follows === true, step.opens);
-      if (!step.follows && !isOn(step.route, where)) return fail(`step ${index + 1}: the browser is on ${where}, not ${step.route}`);
-      const arrived = await judge(where);
+      const shown = await here(step, true);
+      const where = shown?.where ?? await arrive(step.route, step.follows === true, step.opens);
+      if (!shown && !step.follows && !isOn(step.route, where)) return fail(`step ${index + 1}: the browser is on ${where}, not ${step.route}`);
+      const arrived = shown ? null : await judge(where);
       if (arrived) return arrived;
-      let resolution = await find(step, where, true);
+      let resolution = shown?.resolution ?? await find(step, where, true);
       for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await cursor(resting);
         await film();
@@ -3700,7 +4087,7 @@ async function recordClip(options, script, touched) {
       const target = centreOf(resolution.control.box);
       const startedAt = at;
       const action = step.action === "auto" ? actionForRole(resolution.control.role, step.value) : step.action;
-      const typed = step.value ?? step.demo;
+      const typed = step.value ?? step.demo ?? demoValueForField(resolution.control);
       if (action === "fill" && !typed) return fail(`step ${index + 1}: it types into ${resolution.control.name}, and says nothing to type`);
       for (const point of cursorPath(resting, target, MOVE_FRAMES)) {
         await cursor(point);
@@ -3716,10 +4103,11 @@ async function recordClip(options, script, touched) {
         const unfocused = await focus(target);
         if (unfocused) return fail(`step ${index + 1}: ${unfocused}`);
         await cursor(target, false);
-        for (const chunk of chunksOf(value, Math.max(CHARS_PER_FRAME, Math.ceil(value.length / TYPING_FRAMES)))) {
-          await type(chunk);
+        for (const chunk2 of chunksOf(value, Math.max(CHARS_PER_FRAME, Math.ceil(value.length / TYPING_FRAMES)))) {
+          await type(chunk2);
           await shoot(FRAME_MS);
         }
+        if (!await landed(resolution.control, step, where)) return fail(`step ${index + 1}: what was typed into ${resolution.control.name} did not land, and the field still holds nothing`);
       } else if (action === "select") {
         await pointer({ kind: "select", at: target, value: step.value ?? "" });
       } else {
@@ -3747,9 +4135,9 @@ async function recordClip(options, script, touched) {
       });
     }
     if (script.lands) {
-      const landed = await arrive(script.lands);
-      if (!isOn(script.lands, landed)) return fail(`the last step left the browser on ${landed}, not ${script.lands}`);
-      const seen = await judge(landed);
+      const landed2 = await arrive(script.lands);
+      if (!isOn(script.lands, landed2)) return fail(`the last step left the browser on ${landed2}, not ${script.lands}`);
+      const seen = await judge(landed2);
       if (seen) return seen;
     }
     hold(CLOSING_MS);
@@ -3786,15 +4174,18 @@ async function recordClip(options, script, touched) {
   } catch (error) {
     return fail(error instanceof Error ? error.message : String(error));
   } finally {
-    await page.close().catch(() => void 0);
     await rm(dir, { recursive: true, force: true }).catch(() => void 0);
   }
 }
+function leavesBrowserWaiting(because) {
+  return because.includes(CLIP_LATE) || /execution context was destroyed|because of a navigation/i.test(because);
+}
 var CLIP_BUDGET_MS = 20 * 6e4;
 async function runClips(options) {
   const started = Date.now();
   const outcomes = [];
   let spent;
+  let browser = options.browser;
   for (const [index, script] of options.scripts.entries()) {
     const touched = clipRoutes(script).map((route) => ({
       route,
@@ -3811,9 +4202,16 @@ async function runClips(options) {
     } else if (!options.force && options.held.get(script.id) === fingerprint) {
       outcome = { ...base, status: "unchanged", reason: "neither its steps nor a screen they touch has changed" };
     } else {
-      const result = await recordClip({ ...options, screens: options.screens ?? [...options.frames.keys()] }, script, touched);
+      const result = await recordClip({ ...options, browser, screens: options.screens ?? [...options.frames.keys()] }, script, touched);
       if (!result.ok) {
         outcome = { ...base, status: result.status, reason: result.because };
+        if (options.relaunch && leavesBrowserWaiting(result.because)) {
+          const fresh = await options.relaunch().catch(() => void 0);
+          if (fresh) {
+            if (browser !== options.browser) void browser.close().catch(() => void 0);
+            browser = fresh;
+          }
+        }
       } else {
         const delivered = await options.send(result.clip);
         if (delivered.ok) {
@@ -3835,14 +4233,15 @@ async function runClips(options) {
     outcomes.push(outcome);
     options.onProgress?.(outcome, index + 1, options.scripts.length);
   }
+  if (browser !== options.browser) await Promise.race([browser.close().catch(() => void 0), new Promise((resolve) => setTimeout(resolve, 5e3))]);
   return outcomes;
 }
 function run(binary, args) {
   return new Promise((resolve, reject) => {
     const child = spawn(binary, args, { stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
-    child.stderr.on("data", (chunk) => {
-      stderr = `${stderr}${chunk.toString()}`.slice(-2e3);
+    child.stderr.on("data", (chunk2) => {
+      stderr = `${stderr}${chunk2.toString()}`.slice(-2e3);
     });
     child.on(
       "error",
@@ -3982,10 +4381,10 @@ function leadsToTheSamePlaces(children) {
 }
 function parameterName(segments, depth2) {
   const parent = depth2 > 0 ? segments[depth2 - 1] : "";
-  const base = parent && !parent.startsWith(":") ? singular(parent) : "id";
+  const base = parent && !parent.startsWith(":") ? singular2(parent) : "id";
   return base.replace(/[^a-z0-9]+/gi, "") || "id";
 }
-function singular(word) {
+function singular2(word) {
   const lower = word.toLowerCase();
   if (/(analysis|status|address|series|species)$/.test(lower)) return lower;
   if (lower.endsWith("ies")) return `${lower.slice(0, -3)}y`;
@@ -4045,7 +4444,7 @@ var MISS_STATUS = RECORDING_MISS_STATUS;
 function bodyOf(message) {
   return new Promise((resolve, reject) => {
     const chunks = [];
-    message.on("data", (chunk) => chunks.push(chunk));
+    message.on("data", (chunk2) => chunks.push(chunk2));
     message.on("end", () => resolve(Buffer.concat(chunks)));
     message.on("error", reject);
   });
@@ -4219,18 +4618,12 @@ async function waitForApp(url, deadline, onLog, gaveUp) {
   }
   return false;
 }
-async function stageAgainstRecording(options) {
-  const replay = await replayFrom({
-    cassette: options.cassette,
-    ...options.replayPort ? { port: options.replayPort } : {},
-    onMiss: (miss) => options.onLog?.(`  the recording has no ${miss.method} ${miss.path}${miss.from ? ` (wanted by ${miss.from})` : ""}`)
-  });
-  const variable = options.appEnv ?? DEFAULT_APP_ENV;
+async function startProduct(options) {
   let app;
   let died;
   const clock = options.appCommand ? await productClock(options.pinnedClock) : { env: {} };
   if (options.appCommand) {
-    options.onLog?.(`Starting your product with ${variable}=${replay.url}${clockNote(options.pinnedClock)}`);
+    options.onLog?.(options.starting);
     app = spawn2(options.appCommand, {
       shell: true,
       // Its own process group, so it can be taken down as one.
@@ -4241,22 +4634,19 @@ async function stageAgainstRecording(options) {
       // the address occupied by the last one — and on a build agent, the job
       // never finishes.
       detached: true,
-      env: { ...process.env, [variable]: replay.url, ...clock.env },
+      env: { ...process.env, ...options.env, ...clock.env },
       stdio: ["ignore", "pipe", "pipe"]
     });
-    app.stdout?.on("data", (chunk) => options.onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
-    app.stderr?.on("data", (chunk) => options.onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
+    app.stdout?.on("data", (chunk2) => options.onLog?.(`  [app] ${chunk2.toString().trimEnd()}`));
+    app.stderr?.on("data", (chunk2) => options.onLog?.(`  [app] ${chunk2.toString().trimEnd()}`));
     app.on("exit", (code) => {
       died = code ?? 1;
     });
-  } else {
-    options.onLog?.(`The recording is at ${replay.url}. Start your product with ${variable} set to it.`);
   }
   const up = await waitForApp(options.appUrl, Date.now() + (options.waitMs ?? 6e4), options.onLog, () => died !== void 0);
   if (app) await new Promise((resolve) => setTimeout(resolve, 250));
   if (died === void 0 && app?.exitCode !== null && app?.exitCode !== void 0) died = app.exitCode;
   if (died !== void 0) {
-    await replay.close();
     stop(app);
     await clock.written?.remove();
     throw new Error(
@@ -4266,25 +4656,66 @@ Something else is already answering on ${options.appUrl}. That is almost always
     );
   }
   if (!up) {
-    await replay.close();
     stop(app);
     await clock.written?.remove();
     throw new Error(
-      `${options.appUrl} never answered. ` + (options.appCommand ? "Check the start command above, and that your product listens on that address." : `Start your product with ${variable}=${replay.url}, then run this again.`)
+      `${options.appUrl} never answered. ` + (options.appCommand ? "Check the start command above, and that your product listens on that address." : options.unstarted)
     );
   }
+  return {
+    close: async () => {
+      stop(app);
+      await clock.written?.remove();
+    }
+  };
+}
+async function stageAgainstRecording(options) {
+  const replay = await replayFrom({
+    cassette: options.cassette,
+    ...options.replayPort ? { port: options.replayPort } : {},
+    onMiss: (miss) => options.onLog?.(`  the recording has no ${miss.method} ${miss.path}${miss.from ? ` (wanted by ${miss.from})` : ""}`)
+  });
+  const variable = options.appEnv ?? DEFAULT_APP_ENV;
+  if (!options.appCommand) options.onLog?.(`The recording is at ${replay.url}. Start your product with ${variable} set to it.`);
+  let running;
+  try {
+    running = await startProduct({
+      appUrl: options.appUrl,
+      appCommand: options.appCommand,
+      env: { [variable]: replay.url },
+      pinnedClock: options.pinnedClock,
+      waitMs: options.waitMs,
+      onLog: options.onLog,
+      starting: `Starting your product with ${variable}=${replay.url}${clockNote(options.pinnedClock)}`,
+      unstarted: `Start your product with ${variable}=${replay.url}, then run this again.`
+    });
+  } catch (error) {
+    await replay.close();
+    throw error;
+  }
   return {
     appUrl: options.appUrl,
     replayUrl: replay.url,
     replay,
     cassette: options.cassette,
     close: async () => {
-      stop(app);
+      await running.close();
       await replay.close();
-      await clock.written?.remove();
     }
   };
 }
+async function stageApp(options) {
+  const running = await startProduct({
+    appUrl: options.appUrl,
+    appCommand: options.appCommand,
+    pinnedClock: options.pinnedClock,
+    waitMs: options.waitMs,
+    onLog: options.onLog,
+    starting: `Starting your product with ${options.appCommand}${clockNote(options.pinnedClock)}`,
+    unstarted: ""
+  });
+  return { appUrl: options.appUrl, close: () => running.close() };
+}
 function clockNote(pinnedClock) {
   return pinnedClock ? `, its clock pinned to ${pinnedClock}` : "";
 }
@@ -4325,51 +4756,21 @@ Nothing has been photographed. A run that carried on from here would sign in to
   const named = options.examplesOut ? await examplesFrom(options.examplesOut, onLog) : void 0;
   const examples = named?.examples;
   const clips = named?.clips ?? [];
-  let app;
-  let died;
-  const clock = options.appCommand ? await productClock(options.pinnedClock) : { env: {} };
-  if (options.appCommand) {
-    onLog?.(`Starting your product with ${options.appCommand}${clockNote(options.pinnedClock)}`);
-    app = spawn2(options.appCommand, {
-      shell: true,
-      detached: true,
-      env: { ...process.env, ...clock.env },
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    app.stdout?.on("data", (chunk) => onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
-    app.stderr?.on("data", (chunk) => onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
-    app.on("exit", (code) => {
-      died = code ?? 1;
-    });
-  }
-  const up = await waitForApp(options.appUrl, Date.now() + (options.waitMs ?? 6e4), onLog, () => died !== void 0);
-  if (app) await new Promise((resolve) => setTimeout(resolve, 250));
-  if (died === void 0 && app?.exitCode !== null && app?.exitCode !== void 0) died = app.exitCode;
-  if (died !== void 0) {
-    stop(app);
-    await clock.written?.remove();
-    throw new Error(
-      `The start command exited (${died}) before the product was ready. Its output is above.` + (up ? `
-
-Something else is already answering on ${options.appUrl}, which is almost always a server left behind by an earlier run. This will not photograph it, because it is not the product this run started.` : "")
-    );
-  }
-  if (!up) {
-    stop(app);
-    await clock.written?.remove();
-    throw new Error(
-      `${options.appUrl} never answered. Check the start command above, and that your product listens on that address.`
-    );
-  }
+  const running = await startProduct({
+    appUrl: options.appUrl,
+    appCommand: options.appCommand,
+    pinnedClock: options.pinnedClock,
+    waitMs: options.waitMs,
+    onLog,
+    starting: `Starting your product with ${options.appCommand}${clockNote(options.pinnedClock)}`,
+    unstarted: "Check that your product listens on that address."
+  });
   return {
     appUrl: options.appUrl,
     ...sessionPath ? { sessionPath } : {},
     ...examples ? { examples } : {},
     ...clips.length ? { clips } : {},
-    close: async () => {
-      stop(app);
-      await clock.written?.remove();
-    }
+    close: () => running.close()
   };
 }
 async function examplesFrom(path5, onLog) {
@@ -4413,8 +4814,8 @@ async function runToCompletion(command, timeoutMs, env, onLog) {
       stop(child);
       resolve({ ok: false, timedOut: true });
     }, timeoutMs);
-    child.stdout?.on("data", (chunk) => onLog?.(`  [seed] ${chunk.toString().trimEnd()}`));
-    child.stderr?.on("data", (chunk) => onLog?.(`  [seed] ${chunk.toString().trimEnd()}`));
+    child.stdout?.on("data", (chunk2) => onLog?.(`  [seed] ${chunk2.toString().trimEnd()}`));
+    child.stderr?.on("data", (chunk2) => onLog?.(`  [seed] ${chunk2.toString().trimEnd()}`));
     child.on("error", (error) => {
       clearTimeout(timer);
       onLog?.(`  [seed] ${error.message}`);
@@ -4652,6 +5053,34 @@ function depth(path5) {
   return path5 === "/" ? 0 : path5.split("/").filter(Boolean).length;
 }
 
+// core/discovery/apps.ts
+var ROOT_SHARE = 0.8;
+function appRoot(routes) {
+  const screens = documentable(routes);
+  const root = [];
+  for (; ; ) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const route of screens) {
+      const segments = staticSegments(route.path);
+      const next = segments[root.length];
+      if (next && root.every((segment2, index) => segments[index] === segment2)) counts.set(next, (counts.get(next) ?? 0) + 1);
+    }
+    const [segment, count = 0] = [...counts].sort((a, b) => b[1] - a[1])[0] ?? [];
+    if (!segment || count < Math.max(3, screens.length * ROOT_SHARE)) return root;
+    root.push(segment);
+  }
+}
+function belowAppRoot(path5, root) {
+  const segments = path5.split("/").filter(Boolean);
+  return root.length && root.every((segment, index) => segments[index] === segment) ? segments.slice(root.length) : segments;
+}
+function staticSegments(path5) {
+  return path5.split("/").filter((segment) => segment && !segment.startsWith("["));
+}
+function documentable(routes) {
+  return routes.filter((route) => !route.skipped);
+}
+
 // core/discovery/article-plan.ts
 var MONEY_OR_ACCESS = /* @__PURE__ */ new Set([
   "billing",
@@ -4730,15 +5159,15 @@ function slugFor(path5) {
   const segments = path5.split("/").filter(Boolean).filter((segment) => !segment.startsWith("["));
   return segments.length ? segments.join("/") : "overview";
 }
-function titleFor(route) {
-  const segments = route.path.split("/").filter(Boolean).filter((s) => !s.startsWith("["));
-  if (!segments.length) return "Getting around";
+function titleFor(route, root) {
+  const segments = belowAppRoot(route.path, root).filter((s) => !s.startsWith("["));
+  if (!segments.length) return route.params.length ? "Working with a record" : "Getting around";
   const words = segments[segments.length - 1].replace(/[-_]/g, " ");
   const subject = words.charAt(0).toUpperCase() + words.slice(1);
   if (!route.params.length) return subject;
-  return `Working with ${article(singular2(subject.toLowerCase()))}`;
+  return `Working with ${article(singular3(subject.toLowerCase()))}`;
 }
-function singular2(word) {
+function singular3(word) {
   if (/(sis|ss|us|is)$/.test(word)) return word;
   if (/(ches|shes|xes|zes)$/.test(word)) return word.slice(0, -2);
   if (/[^aeiou]ies$/.test(word)) return `${word.slice(0, -3)}y`;
@@ -4784,6 +5213,7 @@ function buildArticlePlan(options) {
     }
   }
   let covered = 0;
+  const root = appRoot(options.routes);
   const needs = [...merged.entries()].map(([slug, group], index) => {
     const rank = index + 1;
     const claimed = [group.entry.route.path, ...group.routes.slice(1) ?? []].map((path5) => options.documented?.[path5]).find(Boolean);
@@ -4791,7 +5221,7 @@ function buildArticlePlan(options) {
     if (already) covered += 1;
     return {
       slug,
-      title: group.title ?? titleFor(group.entry.route),
+      title: group.title ?? titleFor(group.entry.route, root),
       route: group.entry.route.path,
       ...group.routes.length > 1 ? { alsoCovers: group.routes.slice(1) } : {},
       tier: tierFor(rank, merged.size),
@@ -4826,8 +5256,8 @@ function shotIdFor(route) {
   const parts = route.split("/").filter(Boolean).map((segment) => segment.replace(/^\[+\.{0,3}|\]+$/g, ""));
   return parts.length ? parts.join("-").toLowerCase() : "overview";
 }
-function describe(route, isEntry) {
-  const segments = route.path.split("/").filter(Boolean);
+function describe(route, isEntry, root) {
+  const segments = belowAppRoot(route.path, root);
   const last = segments[segments.length - 1] ?? "";
   const screen = route.title ? `The ${route.title} screen` : last.startsWith("[") ? `The screen for a single ${(segments[segments.length - 2] ?? "record").replace(/s$/, "")}` : last ? `The ${last.replace(/[-_]/g, " ")} screen` : "The home screen";
   return isEntry ? `${screen} as someone arrives on it` : `${screen}, reached from ${segments.slice(0, -1).join("/") || "the top level"}`;
@@ -4845,10 +5275,11 @@ function buildStoryboard(options) {
   const own = [...covered].map((path5) => byPath.get(path5)).filter((route) => Boolean(route) && !route.skipped);
   const ordered = options.inOrder ? own : own.sort((a, b) => a.path.length - b.path.length).concat(beneath.sort((a, b) => a.path.length - b.path.length));
   const limit = options.maxSteps ?? 5;
+  const root = appRoot(options.routes);
   const steps = ordered.slice(0, limit).map((route, index) => ({
     route: route.path,
     shotId: shotIdFor(route.path),
-    depicts: describe(route, index === 0),
+    depicts: describe(route, index === 0, root),
     kind: kindFor(route, index === 0),
     needsExampleFor: route.params
   }));
@@ -4901,7 +5332,7 @@ function parseArgs(argv) {
   if (args.out) {
     args.key ??= "";
     args.to ??= "";
-    if (!args.baseUrl) return "Missing --base-url. That is where your product is running.";
+    if (!args.baseUrl && !args.appCommand && !args.seedCommand && !args.cassette) return "Missing --base-url. That is where your product is running.";
     return args;
   }
   if (!args.key) return "Missing --key, or --out <dir> to keep the frames here instead.";
@@ -5080,6 +5511,7 @@ The seed command named ${args.named} clip(s)${asked ? `, and the help desk's how
   const outcomes = await runClips({
     baseUrl: args.baseUrl,
     browser: args.browser,
+    ...args.relaunch ? { relaunch: args.relaunch } : {},
     encoder: ffmpegEncoder(),
     workDir: path4.join(tmpdir2(), `helpdesk-clips-${process.pid}`),
     clearance: args.clearance,
@@ -5104,6 +5536,9 @@ The seed command named ${args.named} clip(s)${asked ? `, and the help desk's how
       const kb = (bytes) => `${Math.round(bytes / 1024)} KB`;
       const detail = outcome.status === "recorded" ? `${((outcome.durationMs ?? 0) / 1e3).toFixed(1)} s, ${kb(outcome.mp4Bytes ?? 0)} MP4, ${outcome.gifBytes ? `${kb(outcome.gifBytes)} GIF` : "no GIF"}` : outcome.reason ?? "";
       console.log(`${mark} clip ${index}/${total} ${outcome.title}: ${detail}`);
+      if (outcome.status === "refused" || outcome.status === "failed") {
+        for (const line of clipStepLines(args.scripts.find((script) => script.id === outcome.clipId))) console.log(`    ${line}`);
+      }
     }
   });
   if (args.local) {
@@ -5115,15 +5550,30 @@ The seed command named ${args.named} clip(s)${asked ? `, and the help desk's how
     await writeFile3(path4.join(args.local, "clips", "manifest.json"), `${JSON.stringify({ schema: "olomon.clip-manifest/1", clips: kept }, null, 2)}
 `, "utf8");
   }
-  const count = (status) => outcomes.filter((outcome) => outcome.status === status).length;
   console.log(`
-Clips: ${count("recorded")} recorded, ${count("unchanged")} unchanged, ${count("deferred")} deferred, ${count("refused")} refused, ${count("failed")} failed.`);
+Clips: ${clipCounts(countClips(outcomes))}.`);
   const missed = outcomes.filter((outcome) => outcome.status === "refused" || outcome.status === "failed");
   if (missed.length && process.env["GITHUB_ACTIONS"] === "true") {
     console.log(`::warning title=${missed.length} clip(s) not recorded::${missed.map((outcome) => `${outcome.clipId}: ${outcome.reason}`).join("; ")}`);
   }
   return outcomes;
 }
+function countClips(outcomes) {
+  const count = (status) => outcomes.filter((outcome) => outcome.status === status).length;
+  return { recorded: count("recorded"), unchanged: count("unchanged"), deferred: count("deferred"), refused: count("refused"), failed: count("failed") };
+}
+function clipStepLines(script) {
+  if (!script) return [];
+  const line = (step, label) => `${label}: ${step.route} "${step.control.name}"${step.control.role ? ` (${step.control.role})` : ""}${step.control.scope ? ` in ${step.control.scope}` : ""}${step.follows ? ", after the press before it" : ""}`;
+  return [...(script.before ?? []).map((step, index) => line(step, `before ${index + 1}`)), ...script.steps.map((step, index) => line(step, `step ${index + 1}`))];
+}
+function elsewhereLines(thrown) {
+  if (thrown.length === 0) return [];
+  return [
+    "Scripts other sites serve into these screens threw, and no screen was counted as crashed for it:",
+    ...thrown.map((held) => `  ${held.by}, on ${held.screens.length} screen${held.screens.length === 1 ? "" : "s"}: ${held.message}`)
+  ];
+}
 function frameForm(frame) {
   const form = new FormData();
   form.set(
@@ -5218,7 +5668,13 @@ Approve one on the plan page, then run this again.`
       return 1;
     }
   }
-  const baseUrl = parsed.cassette || parsed.seedCommand ? parsed.baseUrl ?? "http://127.0.0.1:3000" : parsed.baseUrl ?? orders.baseUrl;
+  const signedOut = orders.capture?.signedOut === true;
+  if (signedOut && parsed.session) {
+    console.log(`This workspace approved the screens anybody sees with nobody signed in, so ${parsed.session} is not used.
+`);
+    delete parsed.session;
+  }
+  const baseUrl = parsed.cassette || parsed.seedCommand || parsed.appCommand ? parsed.baseUrl ?? "http://127.0.0.1:3000" : parsed.baseUrl ?? orders.baseUrl;
   if (!baseUrl) {
     console.error("No product address. Pass --base-url, or set one on the help desk's plan page.");
     return 2;
@@ -5242,7 +5698,7 @@ Approve one on the plan page, then run this again.`
         examplesOut: path4.join(process.cwd(), "helpdesk-examples.json"),
         onLog: (line) => console.log(line)
       });
-      if (seeded.sessionPath) parsed.session = seeded.sessionPath;
+      if (seeded.sessionPath && !signedOut) parsed.session = seeded.sessionPath;
       else delete parsed.session;
       console.log("");
     } catch (error) {
@@ -5269,6 +5725,16 @@ Approve one on the plan page, then run this again.`
       return 1;
     }
   }
+  let app;
+  if (parsed.appCommand && !seeded && !stage) {
+    try {
+      app = await stageApp({ appUrl: baseUrl, appCommand: parsed.appCommand, ...pinnedClock, onLog: (line) => console.log(line) });
+      console.log("");
+    } catch (error) {
+      console.error(String(error.message));
+      return 1;
+    }
+  }
   const browser = await playwrightBrowser({
     ...parsed.session ? { sessionPath: parsed.session } : {},
     ...parsed.liveClock ? { liveClock: true } : {}
@@ -5291,6 +5757,7 @@ Approve one on the plan page, then run this again.`
     await browser.close();
     await stage?.close();
     await seeded?.close();
+    await app?.close();
     return 2;
   }
   if (stage) {
@@ -5416,6 +5883,7 @@ ${unclassified.join("\n")}`);
       console.log(`
 Written to ${local}: ${kept.length} frame(s) and manifest.json.`);
     }
+    let clips;
     if (parsed.clips) {
       const named = seeded?.clips ?? [];
       const articles = seeded ? articleClipsToRecord(orders.clipScripts, seeded.examples) : { scripts: [], refused: [] };
@@ -5427,10 +5895,14 @@ The help desk's articles ask for ${asked} clip(s), and none is recorded: clips a
       const unrecorded = seeded ? unrecordedLines(articles.refused, Array.isArray(orders.clipsSkipped) ? orders.clipsSkipped : []) : [];
       if (unrecorded.length) console.log(`
 ${unrecorded.join("\n")}`);
-      await recordSeededClips({
+      const recorded = await recordSeededClips({
         scripts: clipsToRecord(named, articles.scripts),
         named: named.length,
         browser,
+        relaunch: () => playwrightBrowser({
+          ...parsed.session ? { sessionPath: parsed.session } : {},
+          ...parsed.liveClock ? { liveClock: true } : {}
+        }),
         baseUrl,
         clearance,
         brands: parsed.brands,
@@ -5441,6 +5913,7 @@ ${unrecorded.join("\n")}`);
         held: new Map((orders.clips ?? []).map((clip) => [clip.id, clip.fingerprint])),
         force: Boolean(parsed.rebaseline)
       });
+      if (recorded.length) clips = countClips(recorded);
     }
     if (report.survey.length) {
       const survey = captureReport(report.survey);
@@ -5461,6 +5934,9 @@ whether they changed. Usually a spinner that never resolves or a looping animati
         );
       }
     }
+    const elsewhere = elsewhereLines(browser.thrownElsewhere?.() ?? []);
+    if (elsewhere.length) console.log(`
+${elsewhere.join("\n")}`);
     const gated = report.outcomes.filter((outcome) => outcome.needsAccount);
     if (gated.length) {
       console.log(
@@ -5498,7 +5974,8 @@ ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
       unchanged: report.unchanged,
       skipped: report.skipped,
       refused: report.refused,
-      failed: report.failed
+      failed: report.failed,
+      ...clips ? { clips } : {}
     };
     if (runId) {
       await told;
@@ -5531,6 +6008,7 @@ ${verdict.sentence}`);
     await browser.close();
     await stage?.close();
     await seeded?.close();
+    await app?.close();
   }
 }
 async function openRun(to, headers, total) {
@@ -5595,7 +6073,10 @@ if (runningAsCommand(import.meta.url)) {
 export {
   articleClipsToRecord,
   clipForm,
+  clipStepLines,
   clipsToRecord,
+  countClips,
+  elsewhereLines,
   frameForm,
   framesOnDisk,
   main,