@olomonhelpdesk2/helpdesk 0.1.13 → 0.1.15

package/helpdesk-capture.mjs

@@ -106,7 +106,12 @@ function readExampleRoutes(raw) {
     }
     paths.set(route, path5);
   }
-  return { ok: true, examples: { paths, refused } };
+  const again = /* @__PURE__ */ new Set();
+  for (const route of Array.isArray(body["again"]) ? body["again"] : []) {
+    if (typeof route === "string" && paths.has(route)) again.add(route);
+    else refused.push({ route: String(route), because: "it is named as safe to open again, but not as a route with a record" });
+  }
+  return { ok: true, examples: { paths, refused, again } };
 }
 function resolveVisit(route, examples) {
   const needs = dynamicSegments(route);
@@ -422,7 +427,7 @@ function preflight(facts) {
     name: "posture",
     ok: true,
     blocking: false,
-    detail: facts.clips ? "read-only for the screenshots; after them, the clips the seed command named press the controls their steps name, in the tenant it built" : "read-only: this navigates and photographs, and activates no control"
+    detail: facts.clips ? "read-only for the screenshots; after them, the clips the seed command named and the articles ask for press the controls their steps name, in the tenant it built" : "read-only: this navigates and photographs, and activates no control"
   });
   if (facts.rebaselineReason) {
     checks.push({
@@ -1298,7 +1303,9 @@ async function phoneFit(page, width) {
         if (content > laid + 1) return { fits: false, because: `it runs ${Math.round(content - laid)}px off the side` };
         const main2 = document.querySelector("main, [role=main]");
         const column = main2 ? main2.getBoundingClientRect().width : laid;
-        return column >= laid * 0.75 ? { fits: true } : { fits: false, because: `its main column is ${Math.round(column)}px of ${laid}px, beside the rest of the layout` };
+        if (column < laid * 0.75) return { fits: false, because: `its main column is ${Math.round(column)}px of ${laid}px, beside the rest of the layout` };
+        const overflow = main2 ? main2.scrollWidth - main2.clientWidth : 0;
+        return overflow > 1 ? { fits: false, because: `its content runs ${Math.round(overflow)}px past its main column` } : { fits: true };
       },
       { width }
     )
@@ -1336,6 +1343,10 @@ import { createHash } from "node:crypto";
 var LAYOUT_MANIFEST_SCHEMA = "helpdesk.layout-manifest/1";
 var PHONE_SUFFIX = "--phone";
 var PHONE_VIEWPORT = { width: 390, height: 844 };
+var PHONE_VIEWPORTS = [PHONE_VIEWPORT, { width: 430, height: 932 }];
+function phoneViewport(width) {
+  return PHONE_VIEWPORTS.find((viewport) => viewport.width === width) ?? PHONE_VIEWPORT;
+}
 var CONTROL_ROLES = [
   "button",
   "link",
@@ -1511,13 +1522,21 @@ function layoutManifestText(manifest) {
 // core/capture/clips.ts
 var CLIP_VIEWPORT = { width: 1280, height: 800 };
 var CLIP_FPS = 10;
-var CLIP_MAX_MS = 3e4;
+var CLIP_MAX_MS = 2e4;
 var CLIP_MAX_STEPS = 12;
 var CLIP_MAX_MP4_BYTES = 3 * 1024 * 1024;
 var CLIP_MAX_GIF_BYTES = 8 * 1024 * 1024;
 var CLIP_GIF_WIDTH = 960;
-var CLIP_ACTIONS = ["click", "fill", "select", "check"];
-var MAX_SCRIPTS = 50;
+var CLIP_ACTIONS = ["click", "fill", "select", "check", "auto"];
+function actionForRole(role, value) {
+  if (role === "textbox" || role === "searchbox") return "fill";
+  if ((role === "combobox" || role === "listbox") && value) return "select";
+  if (role === "checkbox" || role === "radio" || role === "switch") return "check";
+  return "click";
+}
+var MAX_SEEDED_SCRIPTS = 50;
+var CLIP_MAX_ARTICLE_SCRIPTS = 400;
+var CLIP_MAX_LEAD_STEPS = 2 * CLIP_MAX_STEPS;
 var MAX_TEXT2 = 200;
 var MAX_TITLE = 120;
 var MAX_ID = 80;
@@ -1540,21 +1559,40 @@ function readStep(value, at) {
   const says = cleanText(step["says"]);
   const given = step["value"];
   if (!route || !isPathLike(route)) return `step ${at} names no screen`;
-  if (typeof role !== "string" || !CONTROL_ROLES.includes(role)) return `step ${at} names no control role a screen lists`;
+  if (role !== void 0 && (typeof role !== "string" || !CONTROL_ROLES.includes(role))) return `step ${at} names no control role a screen lists`;
   if (!name || name.length > MAX_TEXT2) return `step ${at} names no control`;
-  if (typeof action !== "string" || !CLIP_ACTIONS.includes(action)) return `step ${at} says neither click, fill, select nor check`;
+  if (typeof action !== "string" || !CLIP_ACTIONS.includes(action)) return `step ${at} says neither click, fill, select, check nor auto`;
   if (!says || says.length > MAX_TEXT2) return `step ${at} has no sentence for a reader`;
+  if (role === void 0 && action !== "auto") return `step ${at} says how to act on a control without saying what kind it is`;
   const typed = action === "fill" || action === "select";
-  if (typed && (typeof given !== "string" || !given.trim() || given.length > MAX_TEXT2)) return `step ${at} has nothing to ${action}`;
-  if (!typed && given !== void 0) return `step ${at} gives a value to ${action}, which takes none`;
-  return { route, control: { role, name }, action, ...typed ? { value: given } : {}, says };
+  const valued = typeof given === "string" && given.trim() !== "" && given.length <= MAX_TEXT2;
+  if (typed && !valued) return `step ${at} has nothing to ${action}`;
+  if (action !== "auto" && !typed && given !== void 0) return `step ${at} gives a value to ${action}, which takes none`;
+  if (action === "auto" && given !== void 0 && !valued) return `step ${at} has a value nothing can type`;
+  return {
+    route,
+    control: { ...role === void 0 ? {} : { role }, name },
+    action,
+    ...valued && (typed || action === "auto") ? { value: given } : {},
+    says
+  };
+}
+function readSteps(raw) {
+  const steps = [];
+  for (const [index, value] of raw.entries()) {
+    const step = readStep(value, index + 1);
+    if (typeof step === "string") return step;
+    steps.push(step);
+  }
+  return steps;
 }
-function readClipScripts(raw) {
+function readClipScripts(raw, limit = MAX_SEEDED_SCRIPTS) {
   const scripts = [];
   const refused = [];
   if (raw === void 0) return { scripts, refused };
   if (!Array.isArray(raw)) return { scripts, refused: [{ id: "clips", because: "clips is not a list" }] };
-  for (const value of raw.slice(0, MAX_SCRIPTS)) {
+  if (raw.length > limit) refused.push({ id: "clips", because: `${raw.length - limit} clip(s) past the first ${limit} were not read` });
+  for (const value of raw.slice(0, limit)) {
     const script = recordOf2(value);
     const id = typeof script["id"] === "string" ? script["id"] : "";
     const label = id || "a clip";
@@ -1579,21 +1617,18 @@ function readClipScripts(raw) {
       refuse(`it has ${rawSteps.length} steps, and a clip has between 1 and ${CLIP_MAX_STEPS}`);
       continue;
     }
-    const steps = [];
-    let problem = "";
-    for (const [index, rawStep] of rawSteps.entries()) {
-      const step = readStep(rawStep, index + 1);
-      if (typeof step === "string") {
-        problem = step;
-        break;
-      }
-      steps.push(step);
+    const rawBefore = script["before"];
+    if (rawBefore !== void 0 && (!Array.isArray(rawBefore) || rawBefore.length > CLIP_MAX_LEAD_STEPS)) {
+      refuse(`its steps before the recording are not a list of at most ${CLIP_MAX_LEAD_STEPS}`);
+      continue;
     }
-    if (problem) {
-      refuse(problem);
+    const steps = readSteps(rawSteps);
+    const before = readSteps(rawBefore ?? []);
+    if (typeof steps === "string" || typeof before === "string") {
+      refuse(typeof before === "string" ? `before the recording, ${before}` : steps);
       continue;
     }
-    const first = steps[0];
+    const first = before[0] ?? steps[0];
     if (!isPathLike(visit) || !fillsPattern(first.route, visit.split("?")[0])) {
       refuse(`it opens at ${visit || "nowhere"}, which is not ${first.route}`);
       continue;
@@ -1602,17 +1637,19 @@ function readClipScripts(raw) {
       refuse("it names no screen to land on");
       continue;
     }
-    scripts.push({ id, title, visit, steps, ...lands ? { lands } : {} });
+    scripts.push({ id, title, visit, ...before.length ? { before } : {}, steps, ...lands ? { lands } : {} });
   }
   return { scripts, refused };
 }
 function resolveStep(manifest, step) {
   const name = cleanText(step.control.name).toLowerCase();
   const where = manifest.screen.path;
-  const matches = manifest.controls.filter((control) => control.role === step.control.role && control.name.toLowerCase() === name);
-  if (matches.length === 0) return { ok: false, because: `no ${step.control.role} "${step.control.name}" on ${where}` };
-  if (matches.length > 1) return { ok: false, because: `${matches.length} of ${step.control.role} "${step.control.name}" on ${where}, so the step does not say which` };
-  if (matches[0].state?.disabled) return { ok: false, because: `${step.control.role} "${step.control.name}" on ${where} is disabled` };
+  const role = step.control.role;
+  const what = role ?? "control";
+  const matches = manifest.controls.filter((control) => (!role || control.role === role) && control.name.toLowerCase() === name);
+  if (matches.length === 0) return { ok: false, because: `no ${what} "${step.control.name}" on ${where}` };
+  if (matches.length > 1) return { ok: false, because: `${matches.length} of ${what} "${step.control.name}" on ${where}, so the step does not say which` };
+  if (matches[0].state?.disabled) return { ok: false, because: `${what} "${step.control.name}" on ${where} is disabled` };
   return { ok: true, control: matches[0] };
 }
 function onScreen(route, location2) {
@@ -1622,19 +1659,22 @@ function clipRoutes(script) {
   return [.../* @__PURE__ */ new Set([...script.steps.map((step) => step.route), ...script.lands ? [script.lands] : []])];
 }
 function clipFingerprint(script, touched) {
+  const stepsOf = (steps) => steps.map((step) => ({
+    route: step.route,
+    role: step.control.role ?? null,
+    name: step.control.name,
+    action: step.action,
+    value: step.value ?? null,
+    says: step.says
+  }));
   const canonical = {
     version: 1,
     id: script.id,
     title: script.title,
     lands: script.lands ?? null,
-    steps: script.steps.map((step) => ({
-      route: step.route,
-      role: step.control.role,
-      name: step.control.name,
-      action: step.action,
-      value: step.value ?? null,
-      says: step.says
-    })),
+    // Only when there are some, so a clip with none keeps the fingerprint it had before steps could come first.
+    ...script.before?.length ? { before: stepsOf(script.before) } : {},
+    steps: stepsOf(script.steps),
     touched: [...touched].map((screen) => [screen.route, screen.shotId, screen.sha256]).sort((left, right) => String(left[0]).localeCompare(String(right[0])))
   };
   return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
@@ -2584,7 +2624,7 @@ async function runCapture(options) {
   const evidence = [];
   const build = await options.browser.build?.().catch(() => void 0);
   for (const [index, shot] of options.shots.entries()) {
-    const taken = await captureOne(options, shot, build);
+    const taken = shot.variant === "phone" ? await captureAtPhoneWidths(options, shot, build) : await captureOne(options, shot, build);
     const outcome = shot.variant ? { ...taken.outcome, variant: shot.variant } : taken.outcome;
     outcomes.push(outcome);
     if (taken.observed && !shot.variant) survey.push(taken.observed);
@@ -2632,6 +2672,19 @@ async function layoutOf(page, shot, options, cover, size, landed) {
     return void 0;
   }
 }
+async function captureAtPhoneWidths(options, shot, build) {
+  const tried = [];
+  let taken;
+  for (const { width } of PHONE_VIEWPORTS) {
+    taken = await captureOne(options, { ...shot, phoneWidth: width }, build);
+    if (taken.unfit === void 0) return taken;
+    tried.push(`at ${width}px ${taken.unfit}`);
+  }
+  return {
+    ...taken,
+    outcome: { ...taken.outcome, reason: `not laid out for a phone (${tried.join("; ")}), so there is no phone-width frame` }
+  };
+}
 async function captureOne(options, shot, build) {
   if (shot.unvisitable) {
     return { outcome: { shotId: shot.id, route: shot.route, status: "skipped", reason: shot.unvisitable } };
@@ -2639,7 +2692,7 @@ async function captureOne(options, shot, build) {
   const visit = shot.visit ?? shot.route;
   let page;
   try {
-    page = await options.browser.page(shot.variant ? { variant: shot.variant } : void 0);
+    page = await options.browser.page(shot.variant ? { variant: shot.variant, ...shot.phoneWidth ? { width: shot.phoneWidth } : {} } : void 0);
     await page.goto(new URL(visit, options.baseUrl).toString());
     if (await page.isSignIn()) {
       return {
@@ -2700,9 +2753,10 @@ async function captureOne(options, shot, build) {
           route: shot.route,
           status: "skipped",
           result: observed.result,
-          reason: `not laid out for a phone at ${PHONE_VIEWPORT.width}px (${fit.because}), so there is no phone-width frame`
+          reason: `not laid out for a phone at ${phoneViewport(shot.phoneWidth).width}px (${fit.because}), so there is no phone-width frame`
         },
-        observed
+        observed,
+        unfit: fit.because
       };
     }
     const evidence = shot.variant ? void 0 : await readEvidence(settledPage, shot.route, options, build, visit);
@@ -2769,7 +2823,7 @@ async function captureOne(options, shot, build) {
     });
     const image = frame.value;
     const size = pngSize(image);
-    const minimum = shot.variant === "phone" ? PHONE_VIEWPORT.width * CAPTURE_CONTRACT.stillScale : CAPTURE_CONTRACT.minStillWidth;
+    const minimum = shot.variant === "phone" ? phoneViewport(shot.phoneWidth).width * CAPTURE_CONTRACT.stillScale : CAPTURE_CONTRACT.minStillWidth;
     if (size && size.width < minimum) {
       return {
         outcome: {
@@ -2988,8 +3042,9 @@ async function playwrightBrowser(options = {}) {
   };
   return {
     async page(wanted) {
+      const phone = phoneViewport(wanted?.width);
       const context = await browser.newContext(
-        wanted?.variant === "phone" ? { ...contextOptions, viewport: { ...PHONE_VIEWPORT }, isMobile: true, hasTouch: true } : wanted?.variant === "clip" ? { ...contextOptions, viewport: { ...CLIP_VIEWPORT }, deviceScaleFactor: CAPTURE_CONTRACT.clipScale } : contextOptions
+        wanted?.variant === "phone" ? { ...contextOptions, viewport: { ...phone }, isMobile: true, hasTouch: true } : wanted?.variant === "clip" ? { ...contextOptions, viewport: { ...CLIP_VIEWPORT }, deviceScaleFactor: CAPTURE_CONTRACT.clipScale } : contextOptions
       );
       if (!options.liveClock) {
         await context.addInitScript(freezeScript(CAPTURE_CONTRACT.pinnedClock));
@@ -3068,7 +3123,7 @@ async function playwrightBrowser(options = {}) {
           return readPageLayout(page, cover ?? []);
         },
         async phoneFit() {
-          return phoneFit(page, PHONE_VIEWPORT.width).catch(() => ({ fits: false, because: "the page could not be measured at that width" }));
+          return phoneFit(page, phone.width).catch(() => ({ fits: false, because: "the page could not be measured at that width" }));
         },
         async location() {
           const url = new URL(page.url());
@@ -3330,6 +3385,7 @@ var MOVE_FRAMES = 6;
 var DWELL_MS = 500;
 var PRESS_MS = 200;
 var CHARS_PER_FRAME = 2;
+var TYPING_FRAMES = 12;
 var SETTLE_MS = 3e3;
 var STEP_WAIT_MS = 4e3;
 var CLOSING_MS = 1200;
@@ -3396,11 +3452,75 @@ async function recordClip(options, script, touched) {
       await keep(next, FRAME_MS);
       return true;
     };
+    const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    const measureOn = async (step, where) => resolveStep(
+      buildLayoutManifest(await layout(cover), {
+        shotId: script.id,
+        route: step.route,
+        path: where.split("?")[0],
+        variant: "desktop",
+        image: { ...CLIP_VIEWPORT },
+        origin: new URL(options.baseUrl).origin
+      }),
+      step
+    );
+    const steady = async () => {
+      let previous = await page.screenshot(cover);
+      for (let waited = 0; waited < SETTLE_MS; waited += FRAME_MS) {
+        await pause(FRAME_MS);
+        const next = await page.screenshot(cover);
+        if (sameBytes(next, previous)) return;
+        previous = next;
+      }
+    };
+    const reach = async (route) => {
+      let where = await location2();
+      for (let waited = 0; !onScreen(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
+        await pause(FRAME_MS);
+        where = await location2();
+      }
+      if (onScreen(route, where)) {
+        await page.quiet?.(SETTLE_MS);
+        await steady();
+      }
+      return where;
+    };
+    const lead = async (step) => {
+      const where = await reach(step.route);
+      if (!onScreen(step.route, where)) return `the browser is on ${where}, not ${step.route}`;
+      let resolution = await measureOn(step, where);
+      for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
+        await pause(FRAME_MS);
+        resolution = await measureOn(step, where);
+      }
+      if (!resolution.ok) return resolution.because;
+      const target = centreOf(resolution.control.box);
+      const action = step.action === "auto" ? actionForRole(resolution.control.role, step.value) : step.action;
+      if (action === "fill") {
+        if (!step.value) return `it types into ${resolution.control.name}, and says nothing to type`;
+        await pointer({ kind: "focus", at: target });
+        await type(step.value);
+      } else if (action === "select") {
+        await pointer({ kind: "select", at: target, value: step.value ?? "" });
+      } else {
+        await pointer({ kind: "click", at: target });
+      }
+      await page.quiet?.(SETTLE_MS);
+      await steady();
+      return null;
+    };
     await page.goto(new URL(script.visit, options.baseUrl).toString());
     if (await page.isSignIn()) return refuse("its first screen asked for a sign-in, so this session is not the demo tenant's");
     const opened = await location2();
-    if (!onScreen(script.steps[0].route, opened)) return fail(`it opened on ${opened}, not ${script.steps[0].route}`);
-    const before = await judge(opened);
+    const performedFirst = script.before?.[0] ?? script.steps[0];
+    if (!onScreen(performedFirst.route, opened)) return fail(`it opened on ${opened}, not ${performedFirst.route}`);
+    for (const [index, step] of (script.before ?? []).entries()) {
+      const problem = await lead(step);
+      if (problem) return fail(`before the recording, step ${index + 1}: ${problem}`);
+    }
+    const starting = script.before?.length ? await reach(script.steps[0].route) : opened;
+    if (!onScreen(script.steps[0].route, starting)) return fail(`once the steps before it were done, the browser is on ${starting}, not ${script.steps[0].route}`);
+    const before = await judge(starting);
     if (before) return refuse(before);
     let resting = START;
     let poster;
@@ -3427,26 +3547,17 @@ async function recordClip(options, script, touched) {
       if (!onScreen(step.route, where)) return fail(`step ${index + 1}: the browser is on ${where}, not ${step.route}`);
       const arrived = await judge(where);
       if (arrived) return refuse(arrived);
-      const measure = async () => resolveStep(
-        buildLayoutManifest(await layout(cover), {
-          shotId: script.id,
-          route: step.route,
-          path: where.split("?")[0],
-          variant: "desktop",
-          image: { ...CLIP_VIEWPORT },
-          origin: new URL(options.baseUrl).origin
-        }),
-        step
-      );
-      let resolution = await measure();
+      let resolution = await measureOn(step, where);
       for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await cursor(resting);
         await film();
-        resolution = await measure();
+        resolution = await measureOn(step, where);
       }
       if (!resolution.ok) return fail(`step ${index + 1}: ${resolution.because}`);
       const target = centreOf(resolution.control.box);
       const startedAt = at;
+      const action = step.action === "auto" ? actionForRole(resolution.control.role, step.value) : step.action;
+      if (action === "fill" && !step.value) 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);
         await shoot(FRAME_MS);
@@ -3456,14 +3567,15 @@ async function recordClip(options, script, touched) {
       poster ??= frames[frames.length - 1].file;
       await cursor(target, true);
       await shoot(PRESS_MS);
-      if (step.action === "fill") {
+      if (action === "fill") {
+        const value = step.value ?? "";
         await pointer({ kind: "focus", at: target });
         await cursor(target, false);
-        for (const chunk of chunksOf(step.value ?? "", CHARS_PER_FRAME)) {
+        for (const chunk of chunksOf(value, Math.max(CHARS_PER_FRAME, Math.ceil(value.length / TYPING_FRAMES)))) {
           await type(chunk);
           await shoot(FRAME_MS);
         }
-      } else if (step.action === "select") {
+      } else if (action === "select") {
         await pointer({ kind: "select", at: target, value: step.value ?? "" });
       } else {
         await pointer({ kind: "click", at: target });
@@ -3481,9 +3593,9 @@ async function recordClip(options, script, touched) {
       if (after) return refuse(after);
       steps.push({
         route: step.route,
-        role: step.control.role,
+        role: resolution.control.role,
         name: resolution.control.name,
-        action: step.action,
+        action,
         says: step.says,
         atMs: startedAt,
         box: resolution.control.box
@@ -3533,7 +3645,7 @@ async function recordClip(options, script, touched) {
     await rm(dir, { recursive: true, force: true }).catch(() => void 0);
   }
 }
-var CLIP_BUDGET_MS = 10 * 6e4;
+var CLIP_BUDGET_MS = 20 * 6e4;
 async function runClips(options) {
   const started = Date.now();
   const outcomes = [];
@@ -4669,11 +4781,18 @@ function shotsFromRepo(repo, previous) {
     }))
   );
 }
-function withPhoneShots(shots, previous) {
+function withPhoneShots(shots, previous, again = /* @__PURE__ */ new Set()) {
   const planned = new Set(shots.map((shot) => shot.id));
-  const phones = shots.filter((shot) => !shot.visit && !shot.unvisitable && !shot.variant && !planned.has(`${shot.id}${PHONE_SUFFIX}`)).map((shot) => {
+  const phones = shots.filter((shot) => (!shot.visit || again.has(shot.route)) && !shot.unvisitable && !shot.variant && !planned.has(`${shot.id}${PHONE_SUFFIX}`)).map((shot) => {
     const id = `${shot.id}${PHONE_SUFFIX}`;
-    return { id, route: shot.route, depicts: `${shot.depicts}, at phone width`, variant: "phone", ...seenBefore(previous.get(id)) };
+    return {
+      id,
+      route: shot.route,
+      ...shot.visit ? { visit: shot.visit } : {},
+      depicts: `${shot.depicts}, at phone width`,
+      variant: "phone",
+      ...seenBefore(previous.get(id))
+    };
   });
   return [...shots, ...phones];
 }
@@ -4734,6 +4853,28 @@ async function writeLocalClip(dir, clip) {
     durationMs: clip.recording.durationMs
   };
 }
+function articleClipsToRecord(raw, examples) {
+  if (!Array.isArray(raw)) return readClipScripts(raw, CLIP_MAX_ARTICLE_SCRIPTS);
+  const named = examples ?? { paths: /* @__PURE__ */ new Map(), refused: [] };
+  const unopened = [];
+  const opened = raw.map((value) => {
+    const script = typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+    const visit = typeof script["visit"] === "string" ? script["visit"] : "";
+    const resolved = resolveVisit(visit, named);
+    if (!("needs" in resolved)) return { ...script, visit: resolved.visit };
+    unopened.push({ id: typeof script["id"] === "string" ? script["id"] : "a clip", because: describeMissingExample(visit, resolved.needs) });
+    return void 0;
+  });
+  const read = readClipScripts(
+    opened.filter((value) => value !== void 0),
+    CLIP_MAX_ARTICLE_SCRIPTS
+  );
+  return { scripts: read.scripts, refused: [...unopened, ...read.refused] };
+}
+function clipsToRecord(seeded, articles) {
+  const named = new Set(seeded.map((script) => script.id));
+  return [...seeded, ...articles.filter((script) => !named.has(script.id))];
+}
 function clipForm(clip) {
   const id = clip.recording.clipId;
   const form = new FormData();
@@ -4751,9 +4892,18 @@ async function clipsOnDisk(dir) {
     return /* @__PURE__ */ new Map();
   }
 }
+function unrecordedLines(refused, skipped) {
+  const lines = [
+    ...skipped.map((piece) => `  ${piece.slug ? `${piece.slug}${piece.at ? ` at ${piece.at}` : ""}` : "The help desk"}: ${piece.because}`),
+    ...refused.map((entry) => `  ${entry.id}: ${entry.because}`)
+  ];
+  if (!lines.length) return [];
+  const shown = lines.slice(0, 12);
+  return [`${lines.length} piece(s) of the articles' steps are not recorded:`, ...shown, ...lines.length > shown.length ? [`  and ${lines.length - shown.length} more.`] : []];
+}
 async function recordSeededClips(args) {
   if (!args.scripts.length) {
-    console.log("\n--clips was given, but the seed command named no clips, so none were recorded.");
+    console.log("\n--clips was given, but the seed command named no clips and no article asks for one, so none were recorded.");
     return [];
   }
   if (!await ffmpegAvailable()) {
@@ -4766,9 +4916,12 @@ async function recordSeededClips(args) {
   );
   const previous = args.local ? await clipsOnDisk(args.local) : /* @__PURE__ */ new Map();
   const written = [];
-  console.log(`
-The seed command named ${args.scripts.length} clip(s). Each is recorded in the demo tenant it built when it is new or something it shows has changed.
-`);
+  const asked = args.scripts.length - args.named;
+  console.log(
+    `
+The seed command named ${args.named} clip(s)${asked ? `, and the help desk's how-to and troubleshooting articles ask for ${asked} more, one for each piece of their steps` : ""}. Each is recorded in the demo tenant the seed built when it is new or something it shows has changed.
+`
+  );
   const outcomes = await runClips({
     baseUrl: args.baseUrl,
     browser: args.browser,
@@ -4943,7 +5096,7 @@ Approve one on the plan page, then run this again.`
     }
   }
   const withRecords = seeded?.examples ? withExamples(shots, seeded.examples) : shots;
-  const planned = seededLast(parsed.phone ? withPhoneShots(withRecords, previous) : withRecords);
+  const planned = seededLast(parsed.phone ? withPhoneShots(withRecords, previous, seeded?.examples?.again) : withRecords);
   if (parsed.cassette) {
     try {
       stage = await stageAgainstRecording({
@@ -4993,7 +5146,7 @@ Approve one on the plan page, then run this again.`
     console.log(`${coverageReport(found, shots.length).join("\n")}
 `);
   }
-  const phones = parsed.phone ? `, each opened at its own address again at ${PHONE_VIEWPORT.width}px wide if it is laid out for a phone` : "";
+  const phones = parsed.phone ? `, each opened at its own address again at phone width (${PHONE_VIEWPORTS.map((viewport) => `${viewport.width}px`).join(", then ")}) if it is laid out for a phone` : "";
   console.log(
     stage ? `Photographing ${shots.length} screen(s) of ${baseUrl}${phones}, served from ${parsed.cassette}.
 ` : `Photographing ${shots.length} screen(s) of ${baseUrl}${phones}.
@@ -5109,8 +5262,19 @@ ${unclassified.join("\n")}`);
 Written to ${local}: ${kept.length} frame(s) and manifest.json.`);
     }
     if (parsed.clips) {
+      const named = seeded?.clips ?? [];
+      const articles = seeded ? articleClipsToRecord(orders.clipScripts, seeded.examples) : { scripts: [], refused: [] };
+      const asked = Array.isArray(orders.clipScripts) ? orders.clipScripts.length : 0;
+      if (!seeded && asked) {
+        console.log(`
+The help desk's articles ask for ${asked} clip(s), and none is recorded: clips are recorded only in a demo tenant a --seed-command built.`);
+      }
+      const unrecorded = seeded ? unrecordedLines(articles.refused, Array.isArray(orders.clipsSkipped) ? orders.clipsSkipped : []) : [];
+      if (unrecorded.length) console.log(`
+${unrecorded.join("\n")}`);
       await recordSeededClips({
-        scripts: seeded?.clips ?? [],
+        scripts: clipsToRecord(named, articles.scripts),
+        named: named.length,
         browser,
         baseUrl,
         clearance,
@@ -5274,13 +5438,16 @@ if (runningAsCommand(import.meta.url)) {
   );
 }
 export {
+  articleClipsToRecord,
   clipForm,
+  clipsToRecord,
   frameForm,
   framesOnDisk,
   main,
   onePerScreen,
   seededLast,
   shotsFromRepo,
+  unrecordedLines,
   withExamples,
   withPhoneShots,
   writeLocalClip,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olomonhelpdesk2/helpdesk",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Reads a product's screens, plans its help articles, and photographs them.",
   "type": "module",
   "engines": {