@olomonhelpdesk2/helpdesk 0.1.15 → 0.1.17

package/helpdesk-capture.mjs

@@ -1561,6 +1561,8 @@ function readStep(value, at) {
   if (!route || !isPathLike(route)) return `step ${at} names no screen`;
   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`;
+  const scope = control["scope"] === void 0 ? void 0 : cleanText(control["scope"]);
+  if (scope !== void 0 && (!scope || scope.length > MAX_TEXT2)) return `step ${at} names a region of the screen with no name`;
   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`;
@@ -1569,12 +1571,14 @@ function readStep(value, at) {
   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`;
+  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`;
   return {
     route,
-    control: { ...role === void 0 ? {} : { role }, name },
+    control: { ...role === void 0 ? {} : { role }, name, ...scope ? { scope } : {} },
     action,
     ...valued && (typed || action === "auto") ? { value: given } : {},
-    says
+    says,
+    ...step["follows"] === true ? { follows: true } : {}
   };
 }
 function readSteps(raw) {
@@ -1633,6 +1637,10 @@ function readClipScripts(raw, limit = MAX_SEEDED_SCRIPTS) {
       refuse(`it opens at ${visit || "nowhere"}, which is not ${first.route}`);
       continue;
     }
+    if (first.follows) {
+      refuse("its first step follows no step before it, and is the screen it opens at");
+      continue;
+    }
     if (lands !== void 0 && !isPathLike(lands)) {
       refuse("it names no screen to land on");
       continue;
@@ -1641,14 +1649,57 @@ function readClipScripts(raw, limit = MAX_SEEDED_SCRIPTS) {
   }
   return { scripts, refused };
 }
+function comparable(text2) {
+  return cleanText(text2).toLowerCase().replace(/(…|\.\.\.)$/, "").trim();
+}
+var CHROME_ROLES = ["navigation", "complementary", "banner", "contentinfo"];
+var IN_CHROME = /\b(sidebar|side bar|menu|navigation|nav bar|top bar|header)\b/i;
+function within(manifest, control, regionIds) {
+  const regions = new Map(manifest.regions.map((region) => [region.id, region]));
+  const seen = /* @__PURE__ */ new Set();
+  for (let id = control.region; id && !seen.has(id); id = regions.get(id)?.parent) {
+    seen.add(id);
+    if (regionIds.has(id)) return true;
+  }
+  return false;
+}
+function namesControl(shown, named) {
+  const have = comparable(shown);
+  const want = comparable(named);
+  return Boolean(want) && (have === want || have.startsWith(`${want} `));
+}
+function inChrome(manifest, control) {
+  const regions = new Map(manifest.regions.map((region) => [region.id, region]));
+  const seen = /* @__PURE__ */ new Set();
+  for (let id = control.region; id && !seen.has(id); id = regions.get(id)?.parent) {
+    seen.add(id);
+    if (CHROME_ROLES.includes(regions.get(id)?.role ?? "")) return true;
+  }
+  return false;
+}
 function resolveStep(manifest, step) {
-  const name = cleanText(step.control.name).toLowerCase();
+  const name = comparable(step.control.name);
   const where = manifest.screen.path;
   const role = step.control.role;
   const what = role ?? "control";
-  const matches = manifest.controls.filter((control) => (!role || control.role === role) && control.name.toLowerCase() === name);
+  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));
+  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));
+    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}` };
-  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.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` };
+  }
   if (matches[0].state?.disabled) return { ok: false, because: `${what} "${step.control.name}" on ${where} is disabled` };
   return { ok: true, control: matches[0] };
 }
@@ -1663,6 +1714,7 @@ function clipFingerprint(script, touched) {
     route: step.route,
     role: step.control.role ?? null,
     name: step.control.name,
+    ...step.control.scope ? { scope: step.control.scope } : {},
     action: step.action,
     value: step.value ?? null,
     says: step.says
@@ -3130,6 +3182,11 @@ async function playwrightBrowser(options = {}) {
           return `${url.pathname}${url.search}`;
         },
         async pointer(action) {
+          if (action.kind === "scroll") {
+            await page.mouse.move(action.at.x, action.at.y);
+            await page.mouse.wheel(0, action.by);
+            return;
+          }
           if (action.kind === "select") {
             const handle = await page.evaluateHandle(({ x, y }) => document.elementFromPoint(x, y), action.at);
             const element = handle.asElement();
@@ -3389,7 +3446,13 @@ var TYPING_FRAMES = 12;
 var SETTLE_MS = 3e3;
 var STEP_WAIT_MS = 4e3;
 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) };
+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) };
+}
 function chunksOf(text2, size) {
   return Array.from({ length: Math.ceil(text2.length / size) }, (_, index) => text2.slice(index * size, (index + 1) * size));
 }
@@ -3453,17 +3516,14 @@ async function recordClip(options, script, touched) {
       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 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 steady = async () => {
       let previous = await page.screenshot(cover);
       for (let waited = 0; waited < SETTLE_MS; waited += FRAME_MS) {
@@ -3473,6 +3533,35 @@ async function recordClip(options, script, touched) {
         previous = next;
       }
     };
+    let resting = START;
+    const find = async (step, where, filming) => {
+      const raw = await layout(cover);
+      const shown = resolveStep(manifestOf(raw, step, where), step);
+      if (shown.ok) return shown;
+      const whole = resolveStep(manifestOf(wholePage(raw), step, where), step);
+      if (!whole.ok) return shown;
+      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) };
+      if (Math.abs(by) < 2) return shown;
+      if (filming) {
+        for (const point of cursorPath(resting, wheel, MOVE_FRAMES)) {
+          await cursor(point);
+          await shoot(FRAME_MS);
+        }
+        resting = wheel;
+      }
+      await pointer({ kind: "scroll", at: wheel, by });
+      if (filming) {
+        await cursor(resting);
+        for (let waited = 0; waited < SETTLE_MS; waited += FRAME_MS) {
+          if (!await film()) break;
+        }
+      } else {
+        await steady();
+      }
+      return resolveStep(manifestOf(await layout(cover), step, where), step);
+    };
     const reach = async (route) => {
       let where = await location2();
       for (let waited = 0; !onScreen(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
@@ -3485,13 +3574,19 @@ async function recordClip(options, script, touched) {
       }
       return where;
     };
+    const settled = async () => {
+      await page.quiet?.(SETTLE_MS);
+      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 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);
+      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}`;
+      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 measureOn(step, where);
+        resolution = await find(step, where, false);
       }
       if (!resolution.ok) return resolution.because;
       const target = centreOf(resolution.control.box);
@@ -3518,40 +3613,40 @@ async function recordClip(options, script, touched) {
       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 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 before = await judge(starting);
     if (before) return refuse(before);
-    let resting = START;
     let poster;
     const steps = [];
-    const arrive = async (route) => {
+    const arrive = async (route, follows = false) => {
       let where = await location2();
-      for (let waited = 0; !onScreen(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
+      for (let waited = 0; !follows && !onScreen(route, where) && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await cursor(resting);
         await film();
         where = await location2();
       }
-      if (!onScreen(route, where)) return where;
+      if (!follows && !onScreen(route, where)) return where;
       await page.quiet?.(SETTLE_MS);
       await cursor(resting);
       for (let waited = 0; waited < SETTLE_MS; waited += FRAME_MS) {
         if (!await film()) break;
       }
-      return where;
+      return follows ? location2() : where;
     };
     await cursor(resting);
     checked.add(await shoot(OPENING_MS));
     for (const [index, step] of script.steps.entries()) {
-      const where = await arrive(step.route);
-      if (!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);
+      if (!step.follows && !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);
-      let resolution = await measureOn(step, where);
+      let resolution = await find(step, where, true);
       for (let waited = 0; !resolution.ok && waited < STEP_WAIT_MS; waited += FRAME_MS) {
         await cursor(resting);
         await film();
-        resolution = await measureOn(step, where);
+        resolution = await find(step, where, true);
       }
       if (!resolution.ok) return fail(`step ${index + 1}: ${resolution.because}`);
       const target = centreOf(resolution.control.box);
@@ -3592,7 +3687,7 @@ async function recordClip(options, script, touched) {
       const after = await judge(now);
       if (after) return refuse(after);
       steps.push({
-        route: step.route,
+        route: performedOn(step, where),
         role: resolution.control.role,
         name: resolution.control.name,
         action,

package/package.json

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