qiksy-mcp 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "MCP bridge for the Qiksy browser extension — expose live QA findings, forms, network and session to any MCP-capable coding agent.",
   "type": "module",
   "bin": {

package/server.mjs

@@ -30,7 +30,7 @@ import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { basename, extname, dirname, isAbsolute, resolve, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { LIBRARIES, datePlan, hintsFor, recipeFor, classifyNode, classifySnapshot, classifyBehaviour } from './widgets.mjs';
+import { LIBRARIES, datePlan, hintsFor, recipeFor, classifyNode, classifySnapshot, classifyBehaviour, diffDigest } from './widgets.mjs';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
 
@@ -1049,6 +1049,40 @@ function pickNode(nodes, want, used, { fieldsOnly = false } = {}) {
   return null;
 }
 
+/**
+ * WHAT A CONTROL SHOWS — as opposed to what it is CALLED.
+ *
+ * The two are the same on most controls and opposite on the one kind this file kept getting wrong:
+ * a listbox trigger with an `aria-label`. The React stand's downshift button is
+ * `getToggleButtonProps({ 'aria-label': 'Signatory role' })`, so `accessibleName` returns "Signatory
+ * role" for ever while the thing a human reads on it is "Director" — judged by its name, a perfect
+ * fill reads as empty and so does a perfect repair (the same trap that reported three correct MUI
+ * dates as failures, 2026-07-30). `qa_read` returns innerText, which is the rendered truth; the
+ * state rides in front of it because a native control keeps its value there (`value="…"`) and has
+ * no text at all.
+ */
+async function shownText(tabId, node) {
+  if (!node) return '';
+  const state = String(node.state || '');
+  /* A CONTROL WITH ITS LIST UP IS NOT READABLE, and this is the one place a guess is forbidden:
+     several libraries render the options INSIDE the trigger's own element, so an open menu puts
+     every option into innerText and "Director" is found in a control that holds nothing — a fill
+     reporting success while nothing landed, which is the failure that has already cost this
+     product two sessions. `expanded` is the page's own word for "the list is up", so the text is
+     not consulted at all; the caller then treats it as not-landed, which is the safe direction. */
+  if (/\bexpanded\b/.test(state)) return state;
+  let txt = '';
+  const byRef = await callExtension('qa_read', { tabId, ref: node.ref, maxChars: 90 }).catch(() => null);
+  if (byRef && byRef.ok !== false) txt = String(byRef.text || '');
+  /* A ref belongs to ONE snapshot and a React re-render detaches what it points at ("ref is
+     stale"); the cssPath is already on the node and survives that. */
+  if (!txt && node.selector) {
+    const bySel = await callExtension('qa_read', { tabId, selector: node.selector, maxChars: 90 }).catch(() => null);
+    if (bySel && bySel.ok !== false) txt = String(bySel.text || '');
+  }
+  return `${state} ${txt}`.trim();
+}
+
 /**
  * Fill a form from a plain { "field label": "value" } object — the shape of the JSON behind the
  * panel's own `{ }` editor and its ⚡Fill button (`Dataset` in engine/dataset.ts).
@@ -1062,7 +1096,7 @@ function pickNode(nodes, want, used, { fieldsOnly = false } = {}) {
  * The unmatched keys come back WITH the page's actual field names. That is the difference between
  * an agent that fixes its own key on the next call and one that starts snapshotting to find out.
  */
-async function fillByNames(tabId, fields, { dryRun, within, verify } = {}) {
+async function fillByNames(tabId, fields, { dryRun, within, verify, advance, next } = {}) {
   const snap = await snapshotUntrapped(tabId, Object.keys(fields || {})[0]);
   rememberSnapshot(tabId, snap);
   let nodes = Array.isArray(snap?.nodes) ? snap.nodes : [];
@@ -1225,7 +1259,7 @@ async function fillByNames(tabId, fields, { dryRun, within, verify } = {}) {
     // The page's own field names, so the next call can use the right key without a round trip.
     out.fieldsOnThePage = nodes.filter((n) => isFieldNode(n) && n.name).map((n) => n.name).slice(0, 40);
   }
-  if (dryRun) return { ...out, dryRun: true };
+  if (dryRun) return { ...out, dryRun: true, ...(advance ? { wouldAdvance: advance } : {}) };
   if (!batch.length) return { ok: false, error: 'none of those keys matched a field on the page', ...out };
 
   const filled = await callExtension('qa_type_many', { tabId, fields: batch }, 60_000);
@@ -1284,21 +1318,100 @@ async function fillByNames(tabId, fields, { dryRun, within, verify } = {}) {
        * context does. The extension's fill engine drives it correctly in about a second, so that is the
        * repair. Re-attempting raw with a longer wait was the wrong reflex: nothing about it was slow. */
       const fastFailed = !hasIt && node && /raw/.test(String(r.via || '')) && (node.role === 'combobox' || node.role === 'searchbox');
-      if (fastFailed) wrong.push({ ...r, engine: true });
+      /* A BUTTON-TRIGGERED LISTBOX — the select that costs four agent calls on every single run.
+       *
+       * downshift's useSelect, Headless UI's Listbox.Button, MUI's Select: a <button> with
+       * aria-haspopup=listbox and its own ul/li menu. The engine drives it by clicking the option,
+       * and on downshift that does NOTHING — a synthetic click carries no mousedown and,
+       * decisively, does not FOCUS, so nothing commits and any key the agent sends next lands on
+       * <body>. Live (2026-07-30) the fill answered ok:true, the step's own validator still said
+       * "still needed: Signatory role", and the agent then spent a snapshot + two presses + a
+       * re-check doing by hand what keyboardPick has done all along — reachable only from pickPath.
+       *
+       * THE GATE IS NARROW ON PURPOSE, because the repair that UNDID a fill (an Ant multi-select
+       * re-clicked and toggled back off — see `rewritable` above) is the one mistake this ladder
+       * may never repeat:
+       *   · role `button` AND tag not `input` — `input[type=file]` reads as role button and an
+       *     upload control is not a listbox;
+       *   · `expanded`/`collapsed` in the state, i.e. the element really carries aria-expanded:
+       *     that is the shape of a popup trigger and not the shape of Next, Save or a chip;
+       *   · it never took a raw write (a button cannot; if `via` says raw this is not our case);
+       *   · and the decisive one — the RENDERED TEXT does not contain the value. The name cannot
+       *     answer here (it is an aria-label), so one qa_read is paid for exactly these nodes and
+       *     for nothing else. Note what this branch does NOT do: it never re-writes a value, so a
+       *     control whose value is merely unreadable cannot be damaged by it — it can only be
+       *     re-picked, and only when it renders nothing of what was asked for. */
+      /* JUDGED BY THE TAG, NOT BY THE ROLE — corrected against a live run (2026-07-30). The branch
+         first shipped requiring role === 'button', and downshift's trigger does not have it: the
+         snapshot reads `aria-haspopup="listbox"` and calls the node a COMBOBOX whose tag is button.
+         So the repair fell through to the combobox branch above ("raw, waited for the options"),
+         which is exactly the path that had already failed — the fill reported ok and the step's own
+         validator still asked for the field. The tag is the honest signal: a <button> cannot take a
+         written value at all, whatever role the page claims for it, so the keyboard is the only way
+         in. `input` is excluded because input[type=file] reads as role button, and an upload
+         control is not a listbox. */
+      const listboxTrigger =
+        !hasIt && node && node.tag === 'button' &&
+        !/raw/.test(String(r.via || '')) && /\b(expanded|collapsed)\b/.test(shown);
+      const showsWanted = listboxTrigger ? norm(await shownText(tabId, node)).includes(want) : false;
+      /* AND IT IS TESTED FIRST. A button-tagged trigger also satisfies the combobox branch below,
+         and whichever runs first wins — that ordering is what made the fix inert on the very
+         control it was written for. */
+      if (listboxTrigger) { if (!showsWanted) wrong.push({ ...r, keyboard: true }); }
+      else if (fastFailed) wrong.push({ ...r, engine: true });
       else if (!hasIt && node && (node.role === 'combobox' || node.role === 'searchbox') && r.via) wrong.push({ ...r, slow: true });
       else if (!hasIt && !showsSomething && node && rewritable) wrong.push(r);
       else if (!hasIt && !showsSomething && node) unreadable.push(r.key);
     }
     const repaired = [];
     for (const r of wrong) {
+      /* THE KEYBOARD REPAIR RESOLVES ITS OWN TARGET, so it has to run BEFORE the three lines below.
+       *
+       * `pickNode(… { fieldsOnly: true })` looks only at form controls and this repair's control is
+       * a <button>: the ordinary ladder finds nothing, hits `continue`, and the field is listed as
+       * disagreed with no repair attempted at all. keyboardPick takes a NAME and does its own
+       * resolution through findClickable — which is exactly why pickPath can call it too. This is a
+       * second door onto the same room, not a second implementation. */
+      if (r.keyboard) {
+        const kb = await keyboardPick(tabId, r.matched || r.key, r.value, { fromHighlight: true });
+        /* It refuses with the menu still up (the `loose < 0` return presses no Escape), and an
+           abandoned popup is the next widget's bug. On SUCCESS Enter has already closed it, and
+           pressing Escape at a page with no popup up is how a wizard inside a modal gets closed
+           underneath us — so the Escape is spent only where there is something to close. */
+        if (!kb.ok) await clearPopups(tabId);
+        else routeMemory.set(routeKey(tabId, r.matched || r.key), 'keyboard');
+        repaired.push({
+          field: r.key,
+          ok: kb.ok === true,
+          via: kb.ok
+            ? 'ArrowDown ×N + Enter at the trigger — this listbox ignores option clicks'
+            : kb.error || 'the keyboard route did not take either',
+          ...(kb.reads ? { reads: kb.reads } : {}),
+          ...(kb.offers ? { offers: kb.offers } : {}),
+          byKeyboard: true,
+        });
+        await new Promise((res) => setTimeout(res, 140));
+        continue;
+      }
       const snapN = await callExtension('qa_snapshot', { tabId }, 30_000);
       rememberSnapshot(tabId, snapN);
       const hit = pickNode(Array.isArray(snapN?.nodes) ? snapN.nodes : [], { name: r.matched || r.key }, new Set(), { fieldsOnly: true });
       if (!hit) continue;
+      /* REPAIR THE WAY THE VALUE WENT IN, NOT THE OTHER WAY. Watched live on the stand
+         (2026-07-30): an Ant TimePicker took "14:30" perfectly through `raw`, the snapshot could
+         not quote the value back (its panel had not committed to the tree yet), the check called
+         that a miss — and the repair went through the ENGINE, whose date path writes an ISO
+         string. The field ended up holding "2026-07-30". A verification that turns a correct
+         value into a wrong one is the most expensive bug this tool can have, so a text field that
+         was filled raw is re-filled raw, with the same string in the same format the field
+         displays. The engine repair stays for the composites it was written for (r.engine). */
+      const rawFilled = /raw/.test(String(r.via || '')) && ['textbox', 'searchbox', 'spinbutton'].includes(hit.node.role);
       const again = r.slow
         ? await callExtension('qa_type', { tabId, ref: hit.node.ref, value: r.value, raw: true, commit: 'Enter', settleMs: 800 }, 20_000)
-        : await callExtension('qa_type', { tabId, ref: hit.node.ref, value: r.value }, 20_000);
-      repaired.push({ field: r.key, ok: again?.ok !== false, via: r.engine ? 'the fill engine (this library commits its own way)' : r.slow ? 'raw, waited for the options' : 'rewritten', ...(again?.stuck !== undefined ? { stuck: again.stuck } : {}) });
+        : rawFilled && !r.engine
+          ? await callExtension('qa_type', { tabId, ref: hit.node.ref, value: r.value, raw: true, commit: 'Enter', blur: true, settleMs: 300 }, 20_000)
+          : await callExtension('qa_type', { tabId, ref: hit.node.ref, value: r.value }, 20_000);
+      repaired.push({ field: r.key, ok: again?.ok !== false, via: r.engine ? 'the fill engine (this library commits its own way)' : r.slow ? 'raw, waited for the options' : rawFilled ? 'written again, verbatim' : 'rewritten', ...(again?.stuck !== undefined ? { stuck: again.stuck } : {}) });
       await new Promise((res) => setTimeout(res, 140));
     }
     if (unreadable.length && !wrong.length) {
@@ -1314,10 +1427,22 @@ async function fillByNames(tabId, fields, { dryRun, within, verify } = {}) {
          that opens the picker and one that reports the form as broken. */
       const stillWrong = repaired.filter((r) => r.ok === false || r.stuck === false).map((r) => r.field);
       const dateish = wrong.filter((r) => /^(day|month|year|hours|minutes|seconds|meridiem)$/i.test(String(r.matched || r.key)));
+      /* SAID ONCE, FOR THE NEXT CALL — not repeated per field. A trigger that only answers the
+         keyboard answers it every time, so an agent about to drive this control itself should press
+         at the trigger rather than click the option, and an agent about to trust a reply about it
+         should know its accessible name will never show the value. Only the ones that actually
+         WORKED are listed: a keyboard attempt that failed is already in `stillWrong`. */
+      /* BY A FLAG, NOT BY A REGEX OVER PROSE. The older repair path also says "at the trigger" in
+         its `via`, so matching the sentence would sometimes name a field repaired by the other
+         route and attach the wrong explanation to it. The flag is set at exactly one place. */
+      const keyboardOnly = repaired.filter((x) => x.ok && x.byKeyboard).map((x) => x.field);
       verified = {
         disagreed: wrong.map((r) => r.key),
         repaired,
         ...(stillWrong.length ? { stillWrong } : {}),
+        ...(keyboardOnly.length
+          ? { keyboardOnly: { fields: keyboardOnly, why: 'a synthetic click on their options carries no mousedown and no focus, so it commits nothing — they were set with ArrowDown ×N + Enter addressed at the TRIGGER (qa_press { ref }), and their accessible name is an aria-label that never shows the value: read them with qa_read, not from the snapshot name' } }
+          : {}),
         ...(dateish.length
           ? { note: 'those are the SECTIONS of a date field (MUI X and friends): the component rewrites them from its own state, so a written value never sticks. Open its calendar instead — qa_click the "Choose <field>" button, switch to the year view, pick the year, step the month, click the day.' }
           : {}),
@@ -1325,7 +1450,268 @@ async function fillByNames(tabId, fields, { dryRun, within, verify } = {}) {
     }
   }
 
-  return { ok: (filled?.filled || 0) > 0, ...out, filled: filled?.filled, total: filled?.total, results: filled?.results, ...(verified ? { verified } : {}) };
+  /* ONE CALL PER STEP — the fill AND the Next, with the gate between them.
+   *
+   * Three independent reviews of today's 40-call run on demo/react landed on the same lever: a
+   * wizard step costs five calls and four of them are bookkeeping — a snapshot to see the step, the
+   * fill, a click on Next, a snapshot to see what the click did. This call already holds everything
+   * those four need, so it presses Next itself and hands the NEXT step's field names back.
+   *
+   * THE GATE IS THE DESIGN, NOT THE CLICK. Advancing past a step that did not take its data is worse
+   * than an extra call: the wizard keeps the half it got, the agent believes the step is behind it,
+   * and the truth surfaces four steps later as a Submit that will not enable. So the control is
+   * refused whenever this fill was anything but clean, and each refusal names its reason.
+   *
+   * `verified.unreadable` is deliberately NOT one of those reasons. A chips field never quotes its
+   * value back to the tree, and reading "cannot be read" as "did not land" is the same mistake that
+   * once made the repair toggle a multi-select back OFF — see the ladder above. */
+  let advancing = null;
+  if (advance) {
+    const failed = (filled?.results || []).filter((r) => r && r.ok === false).length;
+    const blocked = [];
+    if (!((filled?.filled || 0) > 0)) blocked.push('the batch filled nothing');
+    if (failed) blocked.push(`${failed} of the ${batch.length} entries came back ok:false`);
+    if (verified?.stillWrong?.length) blocked.push(`still wrong after the repair: ${verified.stillWrong.join(', ')}`);
+    if (unmatched.length) blocked.push(`these keys matched no control, so their values never went in: ${unmatched.join(', ')}`);
+    if (blocked.length) {
+      advancing = { advanced: { control: advance, clicked: false, ok: false, why: 'not pressed — this fill is not clean', blocked } };
+    } else {
+      /* A FAILING ADVANCE MUST NOT DESTROY THE FILL'S OWN REPORT. `callExtension` REJECTS on a
+         transport error or a timeout, and an exception thrown here would be caught by the tool
+         handler and returned as an error — throwing away the news that the fields went in. */
+      advancing = await advanceAfterFill(tabId, advance, {
+        // The PAGE's names for what was just written, not the dataset's keys: this is what the
+        // after-snapshot is compared against to tell a real step swap from a Next that did nothing.
+        filledNames: resolved.filter((r) => r.value !== 'click').map((r) => r.matched || r.key),
+        wantNext: next !== false,
+      }).catch((e) => ({
+        advanced: { control: advance, clicked: false, ok: false, why: `the advance could not be driven: ${String(e?.message || e)}` },
+      }));
+    }
+  }
+
+  return { ok: (filled?.filled || 0) > 0, ...out, filled: filled?.filled, total: filled?.total, results: filled?.results, ...(verified ? { verified } : {}), ...(advancing || {}) };
+}
+
+/** Required controls that show no value — minus the ones this call just filled.
+ *
+ *  The subtraction is the whole point. A control whose value the tree cannot quote (Ant's chips, a
+ *  portalled trigger) reads as empty here, and naming a field we have just written as "still needed"
+ *  is an invitation to write it again — which on a multi-select TOGGLES IT OFF. That bug is
+ *  documented in the verify ladder above and must not come back through a hint. */
+function stillNeededOn(nodes, filledNames) {
+  const mine = new Set((filledNames || []).map(norm).filter(Boolean));
+  return nodes
+    .filter((n) => isFieldNode(n) && n.name && !mine.has(norm(n.name)))
+    .filter((n) => /required/.test(String(n.state || '')) && !/value=|checked|selected/.test(String(n.state || '')))
+    .map((n) => n.name)
+    .slice(0, 12);
+}
+
+/** Names that mean "this control goes forward" — so the reply can say what to pass as `advance` next. */
+const FORWARD_NAME = /^(next|continue|proceed|forward|submit|finish|complete|done|save|apply|create|confirm|sign)\b/i;
+
+/**
+ * THE STEP YOU ARE NOW ON, in the only currency that survives a re-render: names.
+ *
+ * Deliberately not refs and not a tree. The agent's next call is another qa_fill_json keyed by
+ * label, so a list of labels is exactly what it needs and the cheapest thing to carry — and a ref
+ * would be void by then anyway, because that call takes its own snapshot and renumbers everything.
+ */
+function describeStep(nodes, url) {
+  /* A TRIGGER IS A FIELD even when the snapshot calls it a button. Headless UI's Listbox and
+     downshift's useSelect render `<button aria-haspopup="listbox">`, which fillByNames finds with
+     its second, filter-less look — so leaving it out of the list here would under-report the step
+     it is about to fill. The snapshot does not carry aria-haspopup, but it does carry the expanded
+     state, and a button that can expand is a control with a value, not a navigation button. */
+  const looksField = (n) => isFieldNode(n) || ((n.role === 'button' || n.role === 'link') && /expanded|collapsed/.test(String(n.state || '')));
+  const headings = nodes.filter((n) => n.role === 'heading' && n.name);
+  // h2/h3 first: the h1 is the page, the h2 is the step (demo/react renders `<h2>{step} · …</h2>`).
+  const heading = headings.find((n) => /^h[23]$/.test(n.tag)) || headings[0];
+  const fields = [];
+  for (const n of nodes) {
+    if (fields.length >= 40) break;
+    if (!looksField(n) || !n.name) continue;
+    // The star is cosmetic — norm() strips a trailing one, so the name still works as a key verbatim.
+    fields.push(/required/.test(String(n.state || '')) ? `${n.name} *` : n.name);
+  }
+  const buttons = nodes.filter((n) => (n.role === 'button' || n.role === 'link') && n.name);
+  const forward = [...new Set(buttons.filter((n) => FORWARD_NAME.test(n.name.trim())).map((n) => n.name))].slice(0, 6);
+  return {
+    url,
+    ...(heading ? { title: heading.name } : {}),
+    fields,
+    ...(forward.length ? { advanceLooksLike: forward } : {}),
+    note: 'the controls of the step you are on NOW, read from the snapshot taken after the click — you do not need a qa_snapshot of your own. A trailing * means the control reports itself required and is ignored when matching; two controls with the same label are addressed as "Label" and "Label#2".',
+  };
+}
+
+/**
+ * PRESS THE ADVANCE CONTROL — and be honest about whether the page actually moved.
+ *
+ * Lifted from applyRecipeStep's advance block, which has been right about the hard part since the
+ * first live wizard: THE CONTROL IS RE-RESOLVED, NEVER REUSED. Its ref came from a snapshot taken
+ * before the fill, filling re-renders, and a new snapshot RENUMBERS every ref — that is how a run
+ * once pressed "Back" while the click reported success. A NAME survives both, so it is resolved
+ * here, against a snapshot taken at this moment.
+ *
+ * Two rules this adds, both because the click's own `ok` is worth nothing for this question:
+ *
+ *   1. A DISABLED Next accepts the click and does nothing. The React stand spells it
+ *      `disabled={!!missing[step - 1].length}`, and the snapshot already carries the answer —
+ *      stateOf() emits `disabled` — so the state is READ before clicking instead of inferred after.
+ *      One 400ms retry first: a form that validates on a debounce is still disabled a moment after
+ *      the last write and then enables itself.
+ *   2. "It advanced" is a property of the DIFF. A step swap replaces its fields wholesale, so both
+ *      sides are large — the same evidence the `navigated` behaviour keys on in widgets.mjs. Nothing
+ *      else produces it: a dropdown opening only appends, a validation message only appends. The
+ *      extension caps each side of the diff at 12 nodes, so the thresholds stay small on purpose.
+ */
+async function advanceAfterFill(tabId, advanceName, { filledNames = [], wantNext = true } = {}) {
+  const look = async () => {
+    const s = await callExtension('qa_snapshot', { tabId }, 30_000);
+    rememberSnapshot(tabId, s);
+    const ns = Array.isArray(s?.nodes) ? s.nodes : [];
+    const pool = ns.filter((n) => CLICKABLE_ROLES.has(n.role));
+    /* EXACT FIRST, AND SEPARATELY FROM pickNode's SOFT TIERS. An open react-datepicker puts "Next
+       Month" and "Next Year" in the tree, and a library with a focus trap sets aria-hidden on
+       everything outside its popup — which takes the real Next OUT of the tree entirely. pickNode
+       would then prefix-match "Next" onto "Next Year" and steer the calendar instead of the wizard. */
+    const exact = pool.filter((n) => norm(n.name) === norm(advanceName));
+    return { url: s?.url || '', nodes: ns, hit: exact.length ? { node: exact[0] } : null };
+  };
+  let seen = await look();
+  let loose = false;
+  if (!seen.hit) {
+    /* ESCAPE ONLY WHEN A POPUP IS ACTUALLY OPEN, and this condition is the difference between a
+       recovery and a disaster. A leftover list from the last field aria-hides the rest of the page
+       (Radix, Headless UI), so the real Next is not in the tree at all and one Escape brings it
+       back. But a wizard living in a DISMISSIBLE MODAL answers Escape by closing itself, and
+       everything this call just wrote goes with it. An exact-match miss on its own means almost
+       nothing — "Next step" is not "Next" — so the untrap is spent only when the tree shows an open
+       popup, which a trapped page always does: the popup is the one subtree NOT aria-hidden. */
+    const popupOpen = seen.nodes.some((n) => n.role === 'option' || n.role === 'treeitem' || /expanded/.test(String(n.state || '')));
+    if (popupOpen) {
+      await clearPopups(tabId);
+      seen = await look();
+    }
+    if (!seen.hit) {
+      const pool = seen.nodes.filter((n) => CLICKABLE_ROLES.has(n.role));
+      const soft = pickNode(pool.length ? pool : seen.nodes, { name: advanceName }, new Set());
+      if (soft) {
+        seen = { ...seen, hit: soft };
+        loose = true;
+      }
+    }
+  }
+  if (!seen.hit) {
+    return {
+      advanced: {
+        control: advanceName,
+        clicked: false,
+        ok: false,
+        why: `nothing clickable is called "${advanceName}"`,
+        clickableOnThePage: seen.nodes.filter((n) => CLICKABLE_ROLES.has(n.role) && n.name).map((n) => n.name).slice(0, 20),
+      },
+    };
+  }
+  if (/disabled/.test(String(seen.hit.node.state || ''))) {
+    await new Promise((r) => setTimeout(r, 400));
+    const again = await look();
+    if (again.hit) seen = again;
+  }
+  if (/disabled/.test(String(seen.hit.node.state || ''))) {
+    const need = stillNeededOn(seen.nodes, filledNames);
+    return {
+      advanced: {
+        control: seen.hit.node.name || advanceName,
+        clicked: false,
+        ok: false,
+        why: 'the control is DISABLED — nothing was pressed',
+        note: 'the step has not validated, so pressing it would have reported success and done nothing. Fill what is still missing and call again with the same `advance`.',
+        ...(need.length ? { stillNeeded: need } : {}),
+      },
+    };
+  }
+
+  // Resolved while the memory still holds the PRE-click page, so the journal records the button by
+  // the name a human reads. stepsFromJournal treats a click as the thing that CLOSES a step.
+  const item = targetOf(tabId, seen.hit.node.ref, seen.hit.node.selector);
+  const urlBefore = seen.url;
+  const clicked = await callExtension('qa_click', { tabId, ref: seen.hit.node.ref }, 20_000);
+  if (clicked?.ok === false) {
+    return { advanced: { control: item.name || advanceName, clicked: false, ok: false, why: `the extension refused the click: ${clicked.error || 'no reason given'}` } };
+  }
+  // A wizard mounts the next step's fields once the click settles, and the snapshot below is what
+  // the agent will be told about — so give them the beat applyRecipeStep gives them.
+  await new Promise((r) => setTimeout(r, 450));
+
+  const d = diffDigest(clicked?.changed ?? {});
+  const moved = d.appeared.length >= 1 && d.disappeared.length >= 1;
+  const swapped = d.appeared.length >= 3 && d.disappeared.length >= 3;
+  const s = await callExtension('qa_snapshot', { tabId }, 30_000);
+  const nodesAfter = Array.isArray(s?.nodes) ? s.nodes : [];
+  const urlAfter = s?.url || urlBefore;
+  const routed = !!(urlBefore && urlAfter && urlBefore !== urlAfter);
+  /* THE CORROBORATION THE DIFF CANNOT GIVE: are the fields we just filled still here? A step that
+     swapped took its own controls with it, which covers the small step whose swap does not reach the
+     thresholds above. It is matched against EVERY named node, not just the field-shaped ones, so a
+     trigger that is a button does not read as gone. And it only counts alongside a diff that moved:
+     a select renames itself when it takes a value — during the FILL, not during this click — so on
+     its own it would call a page that never budged a step swap. */
+  const namesAfter = new Set(nodesAfter.filter((n) => n.name).map((n) => norm(n.name)).filter(Boolean));
+  /* ONLY NAMES THAT WERE STILL ON THE PAGE A MOMENT AGO can count as "gone". A trigger whose
+     accessible name IS its value (MUI's role=combobox div, a chips field) renames itself when it
+     takes the value — during the FILL, not during this click — so its old name is already missing
+     before the button is pressed. Counted naively that makes a page which never budged look like a
+     step swap: one relabelled button ("Next" → "Saving…") satisfies `moved`, and fields that went
+     nowhere satisfy `fieldsGone`. Measured against the PRE-click tree, the whole class is gone. */
+  const namesBefore = new Set(seen.nodes.filter((n) => n.name).map((n) => norm(n.name)).filter(Boolean));
+  const wanted = filledNames.map(norm).filter((n) => n && namesBefore.has(n));
+  const gone = wanted.filter((n) => !namesAfter.has(n));
+  const fieldsGone = namesAfter.size > 0 && wanted.length > 0 && gone.length >= Math.ceil(wanted.length * 0.6);
+  const ok = routed || swapped || (moved && fieldsGone);
+
+  const why = [
+    d.appeared.length || d.disappeared.length ? `${d.appeared.length} appeared, ${d.disappeared.length} disappeared` : 'the page did not move',
+    routed ? `the url changed to ${urlAfter}` : '',
+    wanted.length ? `${gone.length} of the ${wanted.length} fields just filled are no longer on the page` : '',
+  ]
+    .filter(Boolean)
+    .join(' · ');
+
+  /* JOURNALLED ONLY IF IT MOVED. stepsFromJournal reads a click as the END of a step and stores it
+     as that step's `advance`; a click that changed nothing ended nothing, and recording it would cut
+     one step of a saved recipe in two. The entry carries the post-click url, which is harmless: a
+     step takes its url from its first FILL, and a click's url is only ever used for the host filter. */
+  /* JOURNALLED BEFORE THE MEMORY MOVES ON. `note` stamps the entry with the url held in snapMemory,
+     and a recipe step is filtered by host — so remembering the after-page first would file a
+     cross-origin advance under the NEW host and drop it from the saved recipe. Only if it moved:
+     stepsFromJournal reads a click as the END of a step, and a click that changed nothing ended
+     nothing — recording it would cut one recipe step in two. */
+  if (ok) note('click', tabId, [item]);
+  rememberSnapshot(tabId, s);
+
+  if (!ok) {
+    const need = stillNeededOn(nodesAfter, filledNames);
+    return {
+      advanced: {
+        control: item.name || advanceName,
+        clicked: true,
+        ok: false,
+        why,
+        note: moved
+          ? 'something changed, but not in the shape of a step swap — you may still be on the same step. Look before you fill anything else.'
+          : 'the control took the click and the page did not move, so you are still on this step: a Next that is not enabled does exactly this. Do not treat the step as done.',
+        ...(loose ? { matchedLoosely: true } : {}),
+        ...(need.length ? { stillNeeded: need } : {}),
+      },
+    };
+  }
+  return {
+    advanced: { control: item.name || advanceName, clicked: true, ok: true, why, ...(loose ? { matchedLoosely: true } : {}) },
+    ...(wantNext ? { next: describeStep(nodesAfter, urlAfter) } : {}),
+  };
 }
 
 /* ── COMPOSITE WIDGETS, DRIVEN FROM HERE ─────────────────────────────────────────
@@ -2093,7 +2479,7 @@ async function pickMonth(tabId, name, month, year) {
  * addressed AT the trigger (`ref`), because keys sent to the focused element land on `<body>` when
  * nothing has focus. Verified: ArrowDown ×2 → Enter → "Director".
  */
-async function keyboardPick(tabId, triggerName, optionText) {
+async function keyboardPick(tabId, triggerName, optionText, { fromHighlight = false } = {}) {
   const trail = [];
   const triggerRef = async () => (await findClickable(tabId, triggerName, null)).hit?.node?.ref;
   await callExtension('qa_press', { tabId, key: 'Escape' }, 15_000).catch(() => {});
@@ -2110,17 +2496,44 @@ async function keyboardPick(tabId, triggerName, optionText) {
   const idx = options.findIndex((n) => norm(n.name) === norm(optionText));
   const loose = idx < 0 ? options.findIndex((n) => norm(n.name).includes(norm(optionText))) : idx;
   if (loose < 0) return { ok: false, error: `"${optionText}" is not among the ${options.length} options this listbox offers`, offers: options.map((n) => n.name).slice(0, 12), trail };
-  trail.push({ optionIndex: loose + 1, of: options.length });
+
+  /* COUNT FROM WHERE THE HIGHLIGHT ACTUALLY IS — but only when the caller says the control may
+     already hold a value. `loose + 1` presses assume the list opens with nothing highlighted: true
+     of an EMPTY control, false of one that already has a selection, because every one of these
+     libraries opens with the current value highlighted. A repair on a field holding "Owner" and
+     asked for "Director" would then arrow straight past it and commit "Manager" — a WRONG value,
+     put there by a repair, which is the worst thing this file can do. The library's own marker is
+     in the snapshot we have just taken (aria-selected → `selected` in state), so the correction
+     costs no extra call and the offset goes in the trail instead of being assumed silently.
+     pickPath deliberately does NOT pass the flag: its trees reach here as a last resort and their
+     `selected` can mean the previous pick rather than the keyboard's position — extension 1.3.0
+     learned that one the hard way ("where the highlight starts is the library's business"). */
+  const from = fromHighlight ? options.findIndex((n) => /\bselected\b/.test(String(n.state || ''))) : -1;
+  const hops = loose - from;
+  trail.push({ optionIndex: loose + 1, of: options.length, ...(from >= 0 ? { highlightedOnOpen: from + 1 } : {}) });
 
   ref = (await triggerRef()) || ref;
-  for (let i = 0; i <= loose; i++) {
-    await callExtension('qa_press', { tabId, key: 'ArrowDown', ref }, 15_000).catch(() => {});
+  const arrow = hops >= 0 ? 'ArrowDown' : 'ArrowUp';
+  for (let i = 0; i < Math.abs(hops); i++) {
+    await callExtension('qa_press', { tabId, key: arrow, ref }, 15_000).catch(() => {});
     await new Promise((r) => setTimeout(r, 130));
   }
   await callExtension('qa_press', { tabId, key: 'Enter', ref }, 15_000).catch(() => {});
   await new Promise((r) => setTimeout(r, 380));
   const after = await findClickable(tabId, triggerName, null);
-  const reads = String(after.hit?.node?.name || '');
+  /* JUDGE BY WHAT IT SHOWS, NOT ONLY BY WHAT IT IS CALLED — otherwise this verb reports failure on
+     the exact control it was written for. downshift's trigger is
+     getToggleButtonProps({ 'aria-label': 'Signatory role' }), and accessibleName (a11y.ts:119)
+     takes aria-label first, so the name still reads "Signatory role" after a PERFECT pick and `ok`
+     comes back false. The name is KEPT and the rendered text ADDED, never swapped: a cascader
+     really does carry its value in its name. The change is monotone — ok can only go false→true —
+     which is what makes it safe for pickPath's two existing callers; there the practical effect is
+     that a keyboard route which already worked stops being reported as a failure and falling
+     through to the click walk. `shownText` refuses to read an EXPANDED control, so an open menu's
+     own option list can never be mistaken for the trigger's value. */
+  const nameNow = String(after.hit?.node?.name || '');
+  const rendered = after.hit?.node ? await shownText(tabId, after.hit.node) : '';
+  const reads = `${nameNow} ${rendered}`.replace(/\s+/g, ' ').trim();
   const ok = norm(reads).includes(norm(optionText));
   return { ok, via: 'keyboard at the trigger', reads: reads.slice(0, 60), trail };
 }
@@ -3092,7 +3505,15 @@ EVERY control kind by name-and-value: native selects, checkboxes, radios, slider
 the ones that look like they need clicking — Radix/shadcn, MUI, Ant and react-select dropdowns,
 typeahead comboboxes, popup date and time pickers (it opens the popover, waits for the options,
 picks the match and checks the trigger changed). A qa_type_many batch where half the entries are
-dropdowns and dates is the normal use, not an edge case. So a wizard step is about three calls:
+dropdowns and dates is the normal use, not an edge case. When you already know the values, a wizard
+step is ONE call:
+  qa_fill_json { fields: { …the whole step… }, advance: "Next" }
+      → fills, verifies, presses Next only if every entry landed, and rides the NEXT step's field
+        names back in \`next.fields\` — so the step after this one needs no snapshot of yours either.
+        \`advanced.ok\` is read off the click's DIFF, never off its ok: a Next that stays disabled
+        until the step validates accepts a click and does nothing, and this says so instead of
+        moving on. It is not pressed at all when an entry failed or a key matched nothing.
+Three calls when you do not know the field names yet, or must pick one control among duplicates:
   qa_snapshot { fields_only: true }                       → the step's controls, not the app
   qa_type_many { fields: [ …every field of the step… ] }  → widgets and all, in order
   qa_click { name: "Next" }                               → its \`changed\` tells you it advanced
@@ -4037,7 +4458,8 @@ server.registerTool(
       'DATE FIELDS BUILT FROM SECTIONS (MUI X DateField/DatePicker: separate Day / Month / Year spans the component owns) cannot be written to at all — the answer will say so under `verified`, and the way in is the calendar: click the "Choose …" button, switch to the year view, pick the year, step the month, click the day. ' +
       'A value of "click" PRESSES the thing instead of filling it — for the parts of a step that take no value: a chip, a custom radio (div role=radio), a switch, a toggle button. { "Climate": "click", "Medium": "click" } goes in the same batch as the text fields. ' +
       'REPEATED LABELS: a form built from a repeated component gives several controls the identical label — address them as "Full name", "Full name#2", "Full name#3", which is the same #N notation the panel\'s own dataset uses, so a dataset copied out of the `{ }` editor works as written. ' +
-      'dry_run:true resolves the keys and fills nothing — read-only, and the cheap way to check a dataset against a page.' +
+      'ONE CALL PER WIZARD STEP: pass `advance: "Next"` and this presses that control after the fill — but only when the fill was clean. It is NOT pressed if an entry came back ok:false, if a key matched nothing, or if a value is still wrong after the repair, and the reply says which of those it was. Whether the page really advanced is decided by the DIFF the click produced (a step swap makes many nodes appear AND disappear), never by the click answering ok: a Next that is disabled until the step validates accepts a click and does nothing — that case is caught before the click, from the control\'s own state, and comes back as `advanced.ok:false` with `stillNeeded`. When it did advance, `next` carries the FIELD NAMES of the step you are now on, so the following step costs no qa_snapshot of your own; pass next:false to leave them out. ' +
+      'dry_run:true resolves the keys and fills nothing — read-only, and the cheap way to check a dataset against a page (with `advance` set it reports `wouldAdvance` and presses nothing).' +
       DRIVE_NOTE,
     inputSchema: {
       tabId: tabIdArg,
@@ -4053,12 +4475,20 @@ server.registerTool(
         .boolean()
         .optional()
         .describe('Default true: after the batch, read the page back and re-write any field whose value did not actually land, one at a time and re-found by name. This is what makes MUI-style multi-section fields and masked inputs work; pass false to skip the check.'),
+      advance: z
+        .string()
+        .optional()
+        .describe('After the fill, click the control with THIS accessible name — "Next", "Continue", "Submit". Resolved by name against a snapshot taken at that moment (a fill re-renders the step, which is what makes a ref taken earlier click the wrong button), skipped entirely when the control reports itself disabled, and refused when anything about the fill was not clean. The reply\'s `advanced.ok` tells you whether the page actually moved, judged by the click\'s diff.'),
+      next: z
+        .boolean()
+        .optional()
+        .describe('Default true when `advance` is set: ride the NEXT step\'s field names back in the same reply (`next.fields`, plus its title and what its forward control is called), so the step after this one costs you no qa_snapshot. Pass false when you do not need them.'),
     },
   },
-  async ({ tabId, fields, within, dry_run, verify }, extra) => {
-    const bar = loader(extra, dry_run ? 'matching the dataset to the page' : 'filling the form');
+  async ({ tabId, fields, within, dry_run, verify, advance, next }, extra) => {
+    const bar = loader(extra, dry_run ? 'matching the dataset to the page' : advance ? 'filling the form, then advancing' : 'filling the form');
     try {
-      return asText(await fillByNames(tabId, fields, { dryRun: dry_run, within, verify }));
+      return asText(await fillByNames(tabId, fields, { dryRun: dry_run, within, verify, advance, next }));
     } catch (e) {
       return asError(e);
     } finally {