@olomonhelpdesk2/helpdesk 0.1.17 → 0.1.18

package/helpdesk-capture.mjs

@@ -248,6 +248,11 @@ function helpdeskCommand(command, args = []) {
 
 // core/capture/classify.ts
 var THIN_TEXT_CHARS = 25;
+var ERROR_PAGE_PHRASES = [
+  /\bapplication error: a (server|client)-side exception has occurred\b/i,
+  /\bthis screen did not load\b/i,
+  /\bdigest\s*:?\s*[\w-]{6,}\s+copy reference\b/i
+];
 var BOUNDARY_PHRASES = [
   /\bsomething went wrong\b/i,
   /\bapplication error\b/i,
@@ -256,8 +261,12 @@ var BOUNDARY_PHRASES = [
   /\binternal server error\b/i,
   /\bthis page (could not|couldn'?t) be loaded\b/i,
   /\bwe('| a)re sorry[ —,-]+something\b/i,
-  /\berror (id|digest)\b/i
+  /\berror (id|digest)\b/i,
+  ...ERROR_PAGE_PHRASES
 ];
+function showsErrorPage(text2) {
+  return ERROR_PAGE_PHRASES.some((phrase) => phrase.test(text2));
+}
 var NOT_FOUND_PHRASES = [
   /\b(page|it) (was )?not found\b/i,
   /\b404\b/,
@@ -1010,6 +1019,7 @@ async function readPaintedMarkup(page, regions) {
           const style = window.getComputedStyle(element);
           if (style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse") return false;
           if (style.display === "contents") return true;
+          if (typeof element.checkVisibility === "function" && !element.checkVisibility()) return false;
           for (const box of Array.from(element.getClientRects())) {
             if (box.width > 0 && box.height > 0) return true;
           }
@@ -1090,6 +1100,7 @@ async function readPageLayout(page, cover = []) {
         };
         const unseen = (element) => {
           if (element.closest('[aria-hidden="true"], [inert]')) return true;
+          if (typeof element.checkVisibility === "function" && !element.checkVisibility()) return true;
           for (let node = element; node; node = node.parentElement) {
             const style = window.getComputedStyle(node);
             if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return true;
@@ -1572,11 +1583,17 @@ function readStep(value, at) {
   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`;
   if (step["follows"] !== void 0 && step["follows"] !== true) return `step ${at} says neither that it follows the step before it nor that it does not`;
+  const demo = step["demo"] === void 0 ? void 0 : cleanText(step["demo"]);
+  const opens = step["opens"] === void 0 ? void 0 : cleanText(step["opens"]);
+  if (demo !== void 0 && (!demo || demo.length > MAX_TEXT2 || action !== "auto" && action !== "fill")) return `step ${at} has a demo value nothing types`;
+  if (opens !== void 0 && (!isPathLike(opens) || !fillsPattern(route, opens.split("?")[0]))) return `step ${at} opens at ${opens || "nowhere"}, which is not ${route}`;
   return {
     route,
     control: { ...role === void 0 ? {} : { role }, name, ...scope ? { scope } : {} },
     action,
     ...valued && (typed || action === "auto") ? { value: given } : {},
+    ...demo ? { demo } : {},
+    ...opens ? { opens } : {},
     says,
     ...step["follows"] === true ? { follows: true } : {}
   };
@@ -1677,7 +1694,7 @@ function inChrome(manifest, control) {
   }
   return false;
 }
-function resolveStep(manifest, step) {
+function resolveStep(manifest, step, options = {}) {
   const name = comparable(step.control.name);
   const where = manifest.screen.path;
   const role = step.control.role;
@@ -1691,16 +1708,18 @@ function resolveStep(manifest, step) {
     const scoped = matches.filter((control) => within(manifest, control, regions));
     if (scoped.length) matches = scoped;
   }
-  if (!role && matches.length > 1) {
-    const chrome = IN_CHROME.test(step.says);
-    const meant = matches.filter((control) => inChrome(manifest, control) === chrome);
-    if (meant.length === 1) matches = meant;
-  }
-  if (matches.length === 0) return { ok: false, because: `no ${what} "${step.control.name}" on ${where}` };
+  const narrow = (keep) => {
+    const kept = matches.filter(keep);
+    if (kept.length === 1) matches = kept;
+  };
+  if (!role && matches.length > 1 && options.after) narrow((control) => within(manifest, control, /* @__PURE__ */ new Set([options.after])));
+  if (!role && matches.length > 1) narrow((control) => inChrome(manifest, control) === IN_CHROME.test(step.says));
+  if (!role && matches.length > 1) narrow((control) => !control.state?.disabled);
+  if (matches.length === 0) return { ok: false, kind: "missing", 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}${scope ? ` in ${scope}` : ""}, so the step does not say which` };
+    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, because: `${what} "${step.control.name}" on ${where} is disabled` };
+  if (matches[0].state?.disabled) return { ok: false, kind: "disabled", because: `${what} "${step.control.name}" on ${where} is disabled` };
   return { ok: true, control: matches[0] };
 }
 function onScreen(route, location2) {
@@ -1715,6 +1734,7 @@ function clipFingerprint(script, touched) {
     role: step.control.role ?? null,
     name: step.control.name,
     ...step.control.scope ? { scope: step.control.scope } : {},
+    ...step.demo ? { demo: step.demo } : {},
     action: step.action,
     value: step.value ?? null,
     says: step.says
@@ -3195,7 +3215,14 @@ async function playwrightBrowser(options = {}) {
             return;
           }
           await page.mouse.click(action.at.x, action.at.y);
-          if (action.kind === "focus") await page.keyboard.press("ControlOrMeta+A");
+          if (action.kind !== "focus") return;
+          const field = await page.evaluate(() => {
+            const focused = document.activeElement;
+            const kind = focused instanceof HTMLInputElement ? focused.type : "";
+            return Boolean(focused && (focused.isContentEditable || focused instanceof HTMLTextAreaElement || focused instanceof HTMLInputElement && !["button", "checkbox", "color", "file", "image", "radio", "range", "reset", "submit"].includes(kind)));
+          });
+          if (!field) throw new Error(`the press at (${action.at.x}, ${action.at.y}) focused no field, so nothing could be typed`);
+          await page.keyboard.press("ControlOrMeta+A");
         },
         async type(text2) {
           await page.keyboard.type(text2);
@@ -3476,20 +3503,22 @@ async function recordClip(options, script, touched) {
     let last = new Uint8Array();
     const judge = async (where) => {
       const route = where.split("?")[0];
-      const verdict = gateFrame(await page.text(), {
+      const text2 = await page.text();
+      if (showsErrorPage(text2)) return fail(`${route} answered with its error page, not the screen`);
+      const verdict = gateFrame(text2, {
         route,
         ...options.brands ? { brands: options.brands } : {},
         ...options.clearance?.expectedBrands?.length ? { expected: options.clearance.expectedBrands } : {}
       });
-      if (!verdict.safe) return verdict.reason ?? `the gate refused ${route}`;
+      if (!verdict.safe) return refuse(verdict.reason ?? `the gate refused ${route}`);
       if (!options.clearance) return null;
       const clearance = options.clearance;
       const reading = await readScreen(page, clearance);
-      if (!reading) return "this browser cannot read a screen against a clearance";
-      if (reading.inventory.unaccounted.length) return `${reading.inventory.unaccounted.length} value(s) on ${route} are outside every region the clearance names`;
+      if (!reading) return refuse("this browser cannot read a screen against a clearance");
+      if (reading.inventory.unaccounted.length) return refuse(`${reading.inventory.unaccounted.length} value(s) on ${route} are outside every region the clearance names`);
       const approved = new Set(clearance.approved);
       const loose = reading.surfaces.filter((surface) => !surface.read && !clearance.covers.includes(surface.where) && !approved.has(surface.where));
-      if (loose.length && !clearance.coverUnnamed) return `${loose.length} surface(s) on ${route} are neither approved nor covered`;
+      if (loose.length && !clearance.coverUnnamed) return refuse(`${loose.length} surface(s) on ${route} are neither approved nor covered`);
       cover = reading.surfaces.filter((surface) => !surface.read && !approved.has(surface.where)).map((surface) => surface.where);
       return null;
     };
@@ -3516,6 +3545,8 @@ async function recordClip(options, script, touched) {
       return true;
     };
     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,
@@ -3534,12 +3565,13 @@ async function recordClip(options, script, touched) {
       }
     };
     let resting = START;
+    let lastRegion;
     const find = async (step, where, filming) => {
       const raw = await layout(cover);
-      const shown = resolveStep(manifestOf(raw, step, where), step);
+      const shown = resolveStep(manifestOf(raw, step, where), step, { after: lastRegion });
       if (shown.ok) return shown;
-      const whole = resolveStep(manifestOf(wholePage(raw), step, where), step);
-      if (!whole.ok) return shown;
+      const whole = resolveStep(manifestOf(wholePage(raw), step, where), step, { after: lastRegion });
+      if (!whole.ok) return whole.kind === "missing" ? shown : whole;
       const box = whole.control.box;
       const by = Math.round(box.y - WHOLE_SHIFT + box.height / 2 - CLIP_VIEWPORT.height * SCROLL_TO);
       const wheel = { x: Math.round(Math.min(Math.max(box.x + box.width / 2, 1), CLIP_VIEWPORT.width - 1)), y: Math.round(CLIP_VIEWPORT.height / 2) };
@@ -3560,15 +3592,20 @@ async function recordClip(options, script, touched) {
       } else {
         await steady();
       }
-      return resolveStep(manifestOf(await layout(cover), step, where), step);
+      return resolveStep(manifestOf(await layout(cover), step, where), step, { after: lastRegion });
     };
-    const reach = async (route) => {
-      let where = await location2();
-      for (let waited = 0; !onScreen(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
+    const open = async (route, opens, where) => {
+      if (!opens || isOn(route, where)) return where;
+      await page.goto(new URL(opens, options.baseUrl).toString());
+      return location2();
+    };
+    const reach = async (route, opens) => {
+      let where = await open(route, opens, await location2());
+      for (let waited = 0; !isOn(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await pause(FRAME_MS);
         where = await location2();
       }
-      if (onScreen(route, where)) {
+      if (isOn(route, where)) {
         await page.quiet?.(SETTLE_MS);
         await steady();
       }
@@ -3579,22 +3616,29 @@ async function recordClip(options, script, touched) {
       await steady();
       return location2();
     };
-    const performedOn = (step, where) => onScreen(step.route, where) ? step.route : [...script.before ?? [], ...script.steps].map((each) => each.route).find((route) => onScreen(route, where)) ?? where.split("?")[0];
+    const focus = (at2) => pointer({ kind: "focus", at: at2 }).then(
+      () => null,
+      (error) => error instanceof Error ? error.message : String(error)
+    );
+    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);
-      if (!step.follows && !onScreen(step.route, where)) return `the browser is on ${where}, not ${step.route}`;
+      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);
       for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await pause(FRAME_MS);
         resolution = await find(step, where, false);
       }
       if (!resolution.ok) return resolution.because;
+      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;
       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);
+        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);
       } else if (action === "select") {
         await pointer({ kind: "select", at: target, value: step.value ?? "" });
       } else {
@@ -3608,26 +3652,29 @@ async function recordClip(options, script, touched) {
     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();
     const performedFirst = script.before?.[0] ?? script.steps[0];
-    if (!onScreen(performedFirst.route, opened)) return fail(`it opened on ${opened}, not ${performedFirst.route}`);
+    if (!onScreen(performedFirst.route, opened)) {
+      if (!options.screens?.some((route) => onScreen(route, opened))) return fail(`it opened on ${opened}, not ${performedFirst.route}`);
+      redirected = { route: performedFirst.route, path: opened.split("?")[0] };
+    }
     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 first = script.steps[0];
-    const starting = !script.before?.length ? opened : first.follows ? await settled() : await reach(first.route);
-    if (!first.follows && !onScreen(first.route, starting)) return fail(`once the steps before it were done, the browser is on ${starting}, not ${first.route}`);
+    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 before = await judge(starting);
-    if (before) return refuse(before);
+    if (before) return before;
     let poster;
     const steps = [];
-    const arrive = async (route, follows = false) => {
-      let where = await location2();
-      for (let waited = 0; !follows && !onScreen(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
+    const arrive = async (route, follows = false, opens) => {
+      let where = follows ? await location2() : await open(route, opens, await location2());
+      for (let waited = 0; !follows && !isOn(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await cursor(resting);
         await film();
         where = await location2();
       }
-      if (!follows && !onScreen(route, where)) return where;
+      if (!follows && !isOn(route, where)) return where;
       await page.quiet?.(SETTLE_MS);
       await cursor(resting);
       for (let waited = 0; waited < SETTLE_MS; waited += FRAME_MS) {
@@ -3638,10 +3685,10 @@ 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);
-      if (!step.follows && !onScreen(step.route, where)) return fail(`step ${index + 1}: the browser is on ${where}, not ${step.route}`);
+      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);
-      if (arrived) return refuse(arrived);
+      if (arrived) return arrived;
       let resolution = await find(step, where, true);
       for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await cursor(resting);
@@ -3649,10 +3696,12 @@ async function recordClip(options, script, touched) {
         resolution = await find(step, where, true);
       }
       if (!resolution.ok) return fail(`step ${index + 1}: ${resolution.because}`);
+      lastRegion = resolution.control.region;
       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`);
+      const typed = step.value ?? step.demo;
+      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);
         await shoot(FRAME_MS);
@@ -3663,8 +3712,9 @@ async function recordClip(options, script, touched) {
       await cursor(target, true);
       await shoot(PRESS_MS);
       if (action === "fill") {
-        const value = step.value ?? "";
-        await pointer({ kind: "focus", at: target });
+        const value = typed ?? "";
+        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);
@@ -3685,7 +3735,7 @@ async function recordClip(options, script, touched) {
       checked.add(frames[frames.length - 1].file);
       const now = await location2();
       const after = await judge(now);
-      if (after) return refuse(after);
+      if (after) return after;
       steps.push({
         route: performedOn(step, where),
         role: resolution.control.role,
@@ -3698,9 +3748,9 @@ async function recordClip(options, script, touched) {
     }
     if (script.lands) {
       const landed = await arrive(script.lands);
-      if (!onScreen(script.lands, landed)) return fail(`the last step left the browser on ${landed}, not ${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);
-      if (seen) return refuse(seen);
+      if (seen) return seen;
     }
     hold(CLOSING_MS);
     checked.add(frames[frames.length - 1].file);
@@ -3761,7 +3811,7 @@ 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, script, touched);
+      const result = await recordClip({ ...options, screens: options.screens ?? [...options.frames.keys()] }, script, touched);
       if (!result.ok) {
         outcome = { ...base, status: result.status, reason: result.because };
       } else {
@@ -4952,11 +5002,21 @@ 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 recordOf3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+  const withOpens = (steps, from) => Array.isArray(steps) ? steps.map((value, index) => {
+    const step = recordOf3(value);
+    const later = from + index > 0 && step["follows"] !== true;
+    const resolved = later && typeof step["route"] === "string" ? resolveVisit(step["route"], named) : void 0;
+    return resolved && "visit" in resolved && resolved.visit.includes("?") ? { ...step, opens: resolved.visit } : value;
+  }) : steps;
   const opened = raw.map((value) => {
-    const script = typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+    const script = recordOf3(value);
     const visit = typeof script["visit"] === "string" ? script["visit"] : "";
     const resolved = resolveVisit(visit, named);
-    if (!("needs" in resolved)) return { ...script, visit: resolved.visit };
+    const lead = Array.isArray(script["before"]) ? script["before"].length : 0;
+    if (!("needs" in resolved)) {
+      return { ...script, visit: resolved.visit, ...lead ? { before: withOpens(script["before"], 0) } : {}, steps: withOpens(script["steps"], lead) };
+    }
     unopened.push({ id: typeof script["id"] === "string" ? script["id"] : "a clip", because: describeMissingExample(visit, resolved.needs) });
     return void 0;
   });

package/package.json

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