@capagents/forgeqe 2.2.1 → 2.2.3

package/py/forgeqe_engine/webrecord_page.py

@@ -0,0 +1,530 @@
+"""
+What the web recorder puts in the page: RECORDER_JS, run in every page in an isolated world (its own globals, the
+page's DOM), so the page's own scripts can neither see nor call the binding it reports through.
+
+- It reports only trusted events (a real person's input, not a script's dispatchEvent). A password field's text is
+  never read.
+- The Recorder panel is docked in the page itself, in the same browser window: a small panel in a corner (drag it
+  elsewhere, or make it a pill), in the top layer above the page's dialogs, in a closed shadow root. Its own clicks and
+  keys are handled here and stopped before the page's listeners, and are never recorded.
+- Everything the panel shows is set as text (textContent), never as HTML. It loads nothing from the network.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+# The leader key, then one letter: what each letter does, as the key bar and the panel's hint show it.
+COMMAND_KEYS = (
+    ("a", "assert", "check an element"),
+    ("v", "variable", "keep a value"),
+    ("w", "wait", "wait for an element"),
+    ("d", "data", "last typed value is test data"),
+    ("n", "note", "add a note"),
+    ("p", "pause", "pause / resume"),
+    ("z", "undo", "undo last step"),
+    ("s", "stop", "stop recording"),
+)
+
+RECORDER_JS = r"""(() => {
+  if (window.top !== window) return;
+  if (globalThis.__fqeRec) return;
+  const CFG = __CONFIG__;
+  const send = (ev) => { try { globalThis[CFG.binding](JSON.stringify(ev)); } catch (e) {} };
+  const norm = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+  // Elements reported to ForgeQE, by number, so it can find each on the page through the DevTools protocol.
+  const els = [];
+  let dropped = 0;
+  const ref = (el) => { els.push(el); if (els.length > 400) { els.splice(0, 100); dropped += 100; } return dropped + els.length - 1; };
+  const elAt = (i) => els[i - dropped] || null;
+
+  // ---- the element a user acts on, and its facts --------------------------------------------------------------
+  const ACT_TAGS = new Set(['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY', 'OPTION', 'LABEL']);
+  const ACT_ROLES = new Set(['button', 'link', 'checkbox', 'radio', 'switch', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'combobox', 'textbox', 'searchbox', 'treeitem', 'slider', 'spinbutton']);
+  const actionable = (e) => {
+    if (!e || e.nodeType !== 1) return false;
+    if (e.tagName === 'A') return e.hasAttribute('href') || ACT_ROLES.has(e.getAttribute('role'));
+    return ACT_TAGS.has(e.tagName) || ACT_ROLES.has(e.getAttribute('role')) || e.isContentEditable && e === editableRoot(e);
+  };
+  const editableRoot = (e) => { let r = e; while (r.parentElement && r.parentElement.isContentEditable) r = r.parentElement; return r; };
+  const control = (node) => {
+    let e = node && node.nodeType === 1 ? node : node && node.parentElement;
+    for (let i = 0, c = e; c && i <= 5; i++, c = c.parentElement) if (actionable(c)) return c;
+    return e;
+  };
+  const TEXT_TYPES = new Set(['', 'text', 'search', 'email', 'tel', 'url', 'number', 'password', 'date', 'time', 'datetime-local', 'month', 'week']);
+  const isField = (e) => !!e && ((e.tagName === 'INPUT' && TEXT_TYPES.has((e.getAttribute('type') || '').toLowerCase())) || e.tagName === 'TEXTAREA' || e.isContentEditable);
+  const isPassword = (e) => !!e && e.tagName === 'INPUT' && (e.getAttribute('type') || '').toLowerCase() === 'password';
+  const autocomplete = (e) => !!e && (e.getAttribute('role') === 'combobox' || e.hasAttribute('aria-autocomplete') || e.hasAttribute('aria-expanded') || e.hasAttribute('list'));
+  const implicitRole = (e) => {
+    const t = e.tagName, type = (e.getAttribute('type') || '').toLowerCase();
+    if (t === 'A') return e.hasAttribute('href') ? 'link' : '';
+    if (t === 'BUTTON' || t === 'SUMMARY') return 'button';
+    if (t === 'SELECT') return e.multiple || e.size > 1 ? 'listbox' : 'combobox';
+    if (t === 'TEXTAREA') return 'textbox';
+    if (t === 'OPTION') return 'option';
+    if (t === 'IMG') return 'img';
+    if (/^H[1-6]$/.test(t)) return 'heading';
+    if (t === 'INPUT') {
+      if (['button', 'submit', 'reset', 'image'].includes(type)) return 'button';
+      if (type === 'checkbox' || type === 'radio') return type;
+      if (type === 'range') return 'slider';
+      if (type === 'number') return 'spinbutton';
+      if (type === 'search') return 'searchbox';
+      if (['', 'text', 'email', 'tel', 'url'].includes(type)) return e.hasAttribute('list') ? 'combobox' : 'textbox';
+    }
+    return '';
+  };
+  const labelText = (e) => {
+    const by = e.getAttribute('aria-labelledby');
+    if (by) { const t = by.split(/\s+/).map((id) => { const x = document.getElementById(id); return x ? x.textContent : ''; }).join(' '); if (norm(t)) return norm(t); }
+    if (e.getAttribute('aria-label')) return norm(e.getAttribute('aria-label'));
+    if (e.labels && e.labels.length) return norm([...e.labels].map((l) => l.textContent).join(' '));
+    return '';
+  };
+  const accName = (e) => {
+    const l = labelText(e);
+    if (l) return l;
+    const t = e.tagName;
+    if (t === 'INPUT') {
+      const type = (e.getAttribute('type') || '').toLowerCase();
+      if (['button', 'submit', 'reset'].includes(type)) return norm(e.value || (type === 'submit' ? 'Submit' : ''));
+      if (type === 'image') return norm(e.getAttribute('alt'));
+      return norm(e.getAttribute('placeholder') || e.getAttribute('title'));
+    }
+    if (t === 'TEXTAREA' || t === 'SELECT') return norm(e.getAttribute('title'));
+    if (t === 'IMG') return norm(e.getAttribute('alt'));
+    const role = e.getAttribute('role') || implicitRole(e);
+    if (['button', 'link', 'heading', 'tab', 'menuitem', 'option', 'checkbox', 'radio', 'switch', 'treeitem'].includes(role)) return norm(e.innerText || e.textContent).slice(0, 120) || norm(e.getAttribute('title'));
+    return norm(e.getAttribute('title'));
+  };
+  const xpath = (e) => { const parts = []; for (; e && e.nodeType === 1; e = e.parentElement) { let i = 1; for (let s = e.previousElementSibling; s; s = s.previousElementSibling) if (s.tagName === e.tagName) i++; parts.unshift(e.tagName.toLowerCase() + '[' + i + ']'); } return parts.join('/'); };
+  const facts = (e) => {
+    const attrs = {};
+    for (const k of CFG.kept) { const v = e.getAttribute(k); if (v) attrs[k] = v; }
+    const name = accName(e);
+    const classes = [...e.classList].filter((c) => /^[A-Za-z_-][\w-]*$/.test(c)).slice(0, 4);
+    return { tag: e.tagName.toLowerCase(), attributes: attrs, classes, xpath: xpath(e), role: e.getAttribute('role') || implicitRole(e), name: name.slice(0, 120), text: name ? '' : norm(e.innerText || e.textContent).slice(0, 120) };
+  };
+  // How many elements each kind of locator for `e` matches right now, counted at the event: ForgeQE checks locators
+  // through the DevTools protocol, but a click that opens another page can take the element away before it looks.
+  const q = (v) => '"' + String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  const visible = (x) => x.getClientRects().length > 0;
+  const count = (sel) => { try { const all = [...document.querySelectorAll(sel)]; const v = all.filter(visible); return (v.length ? v : all).length; } catch (err) { return -1; } };
+  const ROLE_SEL = 'a, button, input, select, textarea, summary, option, img, h1, h2, h3, h4, h5, h6, [role]';
+  const matches = (e, f) => {
+    const out = { attr: {} };
+    for (const [k, v] of Object.entries(f.attributes)) out.attr[k] = count('[' + k + '=' + q(v) + ']');
+    if (f.attributes.name) out.name = count(f.tag + '[name=' + q(f.attributes.name) + ']');
+    if (f.attributes.href) out.href = count('a[href=' + q(f.attributes.href) + ']');
+    if (f.classes.length) out.css = count(f.tag + f.classes.slice(0, 2).map((c) => '.' + c).join(''));
+    const t = f.text || f.name;
+    if (t) out.text = [...document.querySelectorAll('body *')].filter((x) => visible(x) && norm(x.textContent) === t && ![...x.children].some((c) => norm(c.textContent) === t)).length;
+    if (f.role && f.name) {
+      const same = [...document.querySelectorAll(ROLE_SEL)].filter((x) => visible(x) && (x.getAttribute('role') || implicitRole(x)) === f.role);
+      out.role = same.filter((x) => accName(x) === f.name).length;
+      // The names of the others with this role, for a locator by part of the name, counted after the page is gone.
+      if (/\d/.test(f.name)) out.role_names = same.slice(0, 400).map((x) => accName(x).slice(0, 160));
+    }
+    if (f.name) out.label = [...document.querySelectorAll('input, select, textarea, [aria-label]')].filter((x) => labelText(x) === f.name).length;
+    return out;
+  };
+  const shown = (e) => {
+    if (!e) return '';
+    if (e.tagName === 'INPUT' || e.tagName === 'TEXTAREA') return isPassword(e) ? '' : norm(e.value);
+    if (e.tagName === 'SELECT') return norm([...e.selectedOptions].map((o) => o.text).join(', '));
+    return norm(String(e.innerText || e.textContent || '').split('\n').map(norm).filter(Boolean)[0] || '');
+  };
+  const describeEl = (e) => { const f = facts(e); return { id: ref(e), el: f, matches: matches(e, f), url: location.href }; };
+
+  // ---- the Recorder panel, docked in the page, with the pick highlight and the key bar --------------------------------
+  // In the top layer (a popover), above the page's own dialogs, as brand.py's overlay is; a closed shadow root, so the
+  // page's scripts cannot reach in; left out of what the browser agent reads. Every event in it is handled here, in the
+  // isolated world, and stopped before the page's own listeners: the page never sees the Recorder's clicks and keys, so
+  // a focus trap or a key shortcut of the page cannot take them.
+  const host = document.createElement('forgeqe-recorder');
+  host.setAttribute('data-browser-use-exclude', 'true');
+  host.setAttribute('popover', 'manual');
+  host.style.cssText = 'all:initial !important;position:fixed !important;inset:0 !important;width:100vw !important;height:100vh !important;max-width:none !important;max-height:none !important;margin:0 !important;padding:0 !important;border:0 !important;background:transparent !important;overflow:visible !important;pointer-events:none !important;z-index:2147483647 !important;';
+  const root = host.attachShadow({ mode: 'closed' });
+  root.innerHTML = '<style>' +
+    // ForgeQE's report: its colours, font, 28px buttons with 7px corners, the brand focus ring.
+    ':host{--text:#1f2a44;--muted:#5f6b80;--surface:#fff;--surface-2:#f7f9fb;--line:#e3e8ee;--brand:#0074bf;--brand-line:#c7e1f3;--brand-soft:#e9f3fa;--pass:#1b883c;--fail:#c62828;--warn:#9a4a07;' +
+    '--font:"Ubuntu","Segoe UI",-apple-system,BlinkMacSystemFont,Roboto,Helvetica,Arial,sans-serif;--mono:"Ubuntu Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}' +
+    '*{box-sizing:border-box}' +
+    '.panel{position:fixed;right:16px;bottom:16px;width:340px;max-width:calc(100vw - 32px);max-height:min(70vh,560px);display:flex;flex-direction:column;background:var(--surface);color:var(--text);font:13.5px/1.45 var(--font);border:1px solid var(--line);border-radius:10px;box-shadow:0 10px 30px rgba(15,27,61,.22);pointer-events:auto;overflow:hidden}' +
+    '.panel[hidden],.pill[hidden]{display:none}' +
+    '.head{display:flex;align-items:center;gap:8px;padding:8px 10px 8px 12px;border-bottom:1px solid var(--line);background:var(--surface-2);cursor:move;user-select:none}' +
+    '.state{display:inline-flex;align-items:center;gap:6px;font-weight:600;font-size:14px}' +
+    '.state i,.pill i{width:9px;height:9px;border-radius:50%;background:var(--fail);flex:none}' +
+    '.paused .state i,.pill.paused i{background:var(--warn)}' +
+    '.count{flex:1;color:var(--muted);font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}' +
+    'button{font:inherit;font-size:13px;height:28px;padding:0 10px;border:1px solid var(--line);border-radius:7px;background:var(--surface);color:var(--text);cursor:pointer}' +
+    'button:hover{border-color:var(--brand-line);color:var(--brand)}' +
+    'button:focus-visible,select:focus-visible,textarea:focus-visible,input:focus-visible{outline:2px solid var(--brand);outline-offset:2px}' +
+    'button.primary{background:var(--brand);border-color:var(--brand);color:#fff}' +
+    'button.primary:hover{color:#fff;filter:brightness(.92)}' +
+    'button.stop{color:var(--fail)}' +
+    'button.icon{width:28px;padding:0;font-size:16px;line-height:1}' +
+    '.tools{display:flex;flex-wrap:wrap;gap:6px;padding:8px 12px;border-bottom:1px solid var(--line)}' +
+    'ol{list-style:none;margin:0;padding:4px 0;overflow:auto;flex:1;min-height:60px}' +
+    'li{display:grid;grid-template-columns:24px 1fr 24px;gap:6px;padding:4px 8px 4px 12px;align-items:start}' +
+    'li:hover{background:var(--brand-soft)}' +
+    'li .n{color:var(--muted);text-align:right;font-variant-numeric:tabular-nums;font-size:12px;padding-top:2px}' +
+    'li .t{word-break:break-word}' +
+    'li.check .t{color:var(--pass)}' +
+    'li .sub{display:block;color:var(--muted);font-size:12px}' +
+    'li .x{width:24px;height:24px;padding:0;border:none;background:none;color:var(--muted)}' +
+    'li select{font:inherit;font-size:12px;height:24px;margin-top:4px;border:1px solid var(--line);border-radius:6px;background:var(--surface);color:var(--text)}' +
+    'li label{display:flex;align-items:center;gap:6px;margin-top:4px;color:var(--muted);font-size:12px}' +
+    // The test case being recorded: its steps as a checklist, the current one marked.
+    '.casebox{border-bottom:1px solid var(--line);padding:6px 0 8px;max-height:34%;overflow:auto}' +
+    '.casebox[hidden]{display:none}' +
+    '.casehead{margin:0;padding:0 12px 4px;font-size:12px;font-weight:600;color:var(--muted)}' +
+    '.case{padding:0;min-height:0;flex:none}' +
+    '.case li{cursor:pointer;grid-template-columns:24px 1fr auto}' +
+    '.case li.current{background:var(--brand-soft);box-shadow:inset 3px 0 0 var(--brand)}' +
+    '.case .ok{color:var(--pass);font-size:12px;white-space:nowrap}' +
+    '.case .gap{color:var(--warn);font-size:12px;white-space:nowrap}' +
+    '.casebox button{margin:4px 12px 0}' +
+    '.log{margin:0;padding:6px 12px;border-top:1px solid var(--line);color:var(--muted);font-size:12px;min-height:28px}' +
+    '.log.warn{color:var(--warn)}' +
+    '.chat{display:flex;gap:6px;padding:8px 12px;border-top:1px solid var(--line)}' +
+    'textarea{flex:1;font:inherit;font-size:13px;resize:none;height:44px;border:1px solid var(--line);border-radius:7px;padding:5px 8px;background:var(--surface);color:var(--text)}' +
+    '.hint{margin:0;padding:0 12px 8px;color:var(--muted);font-size:12px}' +
+    'kbd{font:11px var(--mono);border:1px solid var(--line);border-radius:4px;padding:0 4px;background:var(--surface-2)}' +
+    '.pill{position:fixed;right:16px;bottom:16px;display:inline-flex;align-items:center;gap:8px;height:32px;padding:0 12px;border-radius:16px;border:1px solid var(--line);background:var(--surface);color:var(--text);font:13px var(--font);box-shadow:0 6px 18px rgba(15,27,61,.2);pointer-events:auto}' +
+    // The pick highlight and the key bar: brand.py's overlay colours and font.
+    '.box{position:fixed;border:2px solid #3ec4ff;background:rgba(62,196,255,.12);border-radius:3px;display:none;pointer-events:none}' +
+    '.tip{position:fixed;left:50%;bottom:18px;transform:translateX(-50%);max-width:min(640px,calc(100vw - 32px));background:rgba(15,27,61,.96);color:#f4f8ff;font:500 13px/1.4 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;padding:8px 12px;border-radius:8px;box-shadow:0 -8px 24px rgba(0,0,0,.28);display:none;pointer-events:none}' +
+    '.tip b{color:#3ec4ff;font-weight:600}' +
+    '</style>' +
+    '<section class="panel" role="region" aria-label="ForgeQE Recorder">' +
+    '<div class="head" data-drag><span class="state" aria-live="polite"><i></i><span class="st">Recording</span></span><span class="count"></span>' +
+    '<button class="icon" data-ui="collapse" aria-label="Make the Recorder small" title="Make small">–</button></div>' +
+    '<div class="tools" role="group" aria-label="Add to the recording">' +
+    '<button data-cmd="assert" title="Pick an element in the page to check">Check</button>' +
+    '<button data-cmd="variable" title="Pick an element whose text later steps use">Variable</button>' +
+    '<button data-cmd="wait" title="Pick an element the test waits for">Wait for</button>' +
+    '<button data-cmd="data" title="The last value you typed becomes test data">Test data</button>' +
+    '<button data-cmd="undo">Undo</button><button data-cmd="pause" class="pause">Pause</button><button data-cmd="stop" class="stop">Stop</button></div>' +
+    '<div class="casebox" hidden><p class="casehead"></p><ol class="case" aria-label="Test case steps"></ol><button data-cmd="case_next">Next case step</button></div>' +
+    '<ol class="steps" aria-label="Recorded steps"></ol>' +
+    '<p class="log" aria-live="polite"></p>' +
+    '<div class="chat"><textarea data-ui="text" aria-label="Describe a check, or start with note: for a note" placeholder="Describe a check: the total shows &quot;$40.00&quot;"></textarea><button class="primary" data-ui="send">Send</button></div>' +
+    '<p class="hint"></p></section>' +
+    '<button class="pill" data-ui="expand" hidden aria-label="Open the Recorder"><i></i><span></span></button>' +
+    '<div class="box"></div><div class="tip"></div>';
+  const $ = (s) => root.querySelector(s);
+  const panel = $('.panel'), pill = $('.pill'), box = $('.box'), tip = $('.tip'), text = $('textarea');
+  const raise = () => { try { if (host.matches(':popover-open')) host.hidePopover(); host.showPopover(); } catch (e) {} };
+  // Inside <html>, never in place of it: the script runs before the page's own document element exists.
+  const mount = () => { if (!host.isConnected && document.documentElement) { document.documentElement.appendChild(host); raise(); } };
+  // A dialog the page opens later goes into the top layer above the Recorder: put the Recorder back on top.
+  new MutationObserver(() => { if (document.querySelector('dialog[open], [popover]:popover-open:not(forgeqe-recorder)')) raise(); }).observe(document, { subtree: true, attributes: true, attributeFilter: ['open'] });
+  let tipTimer = 0;
+  const say = (parts, ms = 2600) => { mount(); tip.textContent = ''; for (const [b, t] of parts) { const s = document.createElement(b ? 'b' : 'span'); s.textContent = t; tip.appendChild(s); } tip.style.display = 'block'; clearTimeout(tipTimer); if (ms) tipTimer = setTimeout(() => { tip.style.display = 'none'; }, ms); };
+  const ours = (ev) => ev.composedPath().includes(host);
+  const el = (tag, cls, t) => { const e = document.createElement(tag); if (cls) e.className = cls; if (t !== undefined) e.textContent = t; return e; };
+
+  let paused = false;
+  let ui = { collapsed: false, x: null, y: null };
+  const place = () => {
+    panel.hidden = ui.collapsed; pill.hidden = !ui.collapsed;
+    for (const p of [panel, pill]) {
+      if (ui.x === null || ui.x === undefined) { p.style.left = p.style.top = p.style.right = p.style.bottom = ''; continue; }
+      const w = p.offsetWidth || 340, h = p.offsetHeight || 32;
+      p.style.left = Math.max(0, Math.min(innerWidth - w, ui.x)) + 'px';
+      p.style.top = Math.max(0, Math.min(innerHeight - h, ui.y)) + 'px';
+      p.style.right = p.style.bottom = 'auto';
+    }
+  };
+  const KINDS = ['text', 'visible', 'hidden', 'value'];
+  const render = (s) => {
+    mount();
+    paused = s.state === 'paused';
+    panel.classList.toggle('paused', paused); pill.classList.toggle('paused', paused);
+    $('.st').textContent = paused ? 'Paused' : s.state === 'stopped' ? 'Stopped' : 'Recording';
+    $('.count').textContent = s.summary || '';
+    $('.pause').textContent = paused ? 'Resume' : 'Pause';
+    pill.querySelector('span').textContent = (paused ? 'Paused' : 'Recording') + (s.summary ? ' · ' + s.summary : '');
+    const hint = $('.hint');
+    hint.textContent = '';
+    hint.append('In the page: ', el('kbd', '', s.leader || ''), ' then ' + CFG.commands.map(([k, , label]) => k.toUpperCase() + ' ' + label).join(', '));
+    const box2 = $('.casebox');
+    box2.hidden = !s.case;
+    if (s.case) {
+      $('.casehead').textContent = 'Test case ' + (s.case.id || '') + ': pick the step you are on';
+      const cl = $('.case');
+      cl.textContent = '';
+      for (const c of s.case.steps || []) {
+        const li = el('li', c.current ? 'current' : '');
+        li.dataset.case = String(c.n);
+        li.setAttribute('aria-current', c.current ? 'step' : 'false');
+        li.append(el('span', 'n', String(c.n)));
+        const t = el('span', 't', c.action);
+        if (c.expected) t.append(el('span', 'sub', 'expects: ' + c.expected));
+        li.append(t, c.expected ? el('span', c.checked ? 'ok' : 'gap', c.checked ? '\u2713 checked' : 'no check yet') : el('span'));
+        cl.append(li);
+      }
+    }
+    const list = $('.steps');
+    const atEnd = list.scrollTop + list.clientHeight >= list.scrollHeight - 8;
+    list.textContent = '';
+    for (const row of s.steps || []) {
+      const li = el('li', row.op === 'expect' ? 'check' : '');
+      li.append(el('span', 'n', String(row.n)));
+      const t = el('span', 't', row.text);
+      if (row.inferred) t.append(el('span', 'sub', 'added: the menu opens on hover'));
+      if (row.note) t.append(el('span', 'sub', 'note: ' + row.note));
+      if (row.case_step && s.case) t.append(el('span', 'sub', 'case step ' + row.case_step));
+      if (row.op === 'expect' && KINDS.includes(row.kind)) {
+        const sel = el('select');
+        sel.setAttribute('aria-label', 'Kind of check for step ' + row.n);
+        sel.dataset.kind = String(row.n);
+        for (const k of KINDS) { const o = el('option', '', k); o.value = k; o.selected = k === row.kind; sel.append(o); }
+        const lab = el('label');
+        const dyn = el('input'); dyn.type = 'checkbox'; dyn.checked = !!row.dynamic; dyn.dataset.dyn = String(row.n);
+        lab.append(dyn, 'live data: check the pattern, not this value');
+        t.append(sel, lab);
+      }
+      if (row.generated) {
+        const lab = el('label');
+        const dyn = el('input'); dyn.type = 'checkbox'; dyn.checked = true; dyn.dataset.dyn = String(row.n);
+        lab.append(dyn, row.generated === 'date' ? 'a date from today on each run (untick: as typed)' : 'new on each run (untick: as typed)');
+        t.append(lab);
+      }
+      li.append(t);
+      if (row.n > 1) { const x = el('button', 'x', '✕'); x.dataset.del = String(row.n); x.title = 'Remove step ' + row.n; x.setAttribute('aria-label', 'Remove step ' + row.n); li.append(x); } else li.append(el('span'));
+      list.append(li);
+    }
+    if (atEnd) list.scrollTop = list.scrollHeight;
+    if (s.ui) ui = { ...ui, ...s.ui };
+    place();
+  };
+  const log = (t, level) => { const p = $('.log'); p.textContent = t; p.classList.toggle('warn', level === 'warn'); };
+  const sendChat = () => { const t = text.value.trim(); if (t) send({ kind: 'command', cmd: 'chat', text: t }); text.value = ''; };
+
+  let drag = null;
+  const PANEL_EVENTS = ['click', 'dblclick', 'auxclick', 'contextmenu', 'mousedown', 'mouseup', 'pointerdown', 'pointerup', 'pointermove', 'mousemove', 'mouseover', 'mouseout', 'keydown', 'keyup', 'keypress', 'beforeinput', 'input', 'change', 'focusin', 'focusout', 'focus', 'blur', 'paste', 'copy', 'cut', 'wheel', 'dragstart', 'submit'];
+  const onPanel = (ev) => {
+    if (drag && (ev.type === 'pointermove' || ev.type === 'pointerup')) {
+      ev.stopImmediatePropagation();
+      if (ev.type === 'pointermove') { ui.x = drag.x + ev.clientX - drag.cx; ui.y = drag.y + ev.clientY - drag.cy; place(); }
+      else { drag = null; send({ kind: 'panel_ui', ui }); }
+      return;
+    }
+    if (!ours(ev)) return;
+    ev.stopImmediatePropagation();
+    if (!ev.isTrusted) return;
+    // A listener outside a closed shadow root sees only its host: the control is the one under the pointer, or, for
+    // keys and changes, the one with focus.
+    const start = 'clientX' in ev ? root.elementFromPoint(ev.clientX, ev.clientY) : root.activeElement;
+    const hit = (attr) => { for (let x = start; x && x !== root; x = x.parentElement || x.parentNode) if (x.nodeType === 1 && x.hasAttribute(attr)) return x; return null; };
+    if (ev.type === 'pointerdown' && hit('data-drag') && !hit('data-ui')) {
+      const r = (ui.collapsed ? pill : panel).getBoundingClientRect();
+      drag = { x: r.left, y: r.top, cx: ev.clientX, cy: ev.clientY };
+      ev.preventDefault();
+      return;
+    }
+    // The key commands work with the focus in the panel too.
+    if (ev.type === 'keydown' && leaderKey(ev)) return;
+    if (ev.type === 'keydown' && root.activeElement === text && ev.key === 'Enter' && !ev.shiftKey) { ev.preventDefault(); sendChat(); return; }
+    if (ev.type === 'change') {
+      const k = hit('data-kind'), d = hit('data-dyn');
+      if (k) send({ kind: 'command', cmd: 'set_kind', n: Number(k.dataset.kind), kind: k.value });
+      if (d) send({ kind: 'command', cmd: 'set_dynamic', n: Number(d.dataset.dyn), dynamic: d.checked });
+      return;
+    }
+    if (ev.type !== 'click') return;
+    const cmd = hit('data-cmd'), u = hit('data-ui'), del = hit('data-del'), cs = hit('data-case');
+    if (cs) { send({ kind: 'command', cmd: 'case_step', n: Number(cs.dataset.case) }); return; }
+    // A button of the panel gives the focus back to the page, so typing and key commands go on there.
+    if ((cmd || del) && root.activeElement) root.activeElement.blur();
+    if (cmd) { if (dirty) flush(); picks(cmd.dataset.cmd); send({ kind: 'command', cmd: cmd.dataset.cmd }); }
+    else if (del) send({ kind: 'command', cmd: 'delete', n: Number(del.dataset.del) });
+    else if (u && u.dataset.ui === 'send') sendChat();
+    else if (u && (u.dataset.ui === 'collapse' || u.dataset.ui === 'expand')) { ui.collapsed = u.dataset.ui === 'collapse'; place(); send({ kind: 'panel_ui', ui }); }
+  };
+  // Added first, so the panel's events stop here before any other listener, ForgeQE's own recording ones included.
+  for (const type of PANEL_EVENTS) window.addEventListener(type, onPanel, true);
+
+  // ---- picking an element for a check, a variable, or a wait ---------------------------------------------------
+  let picking = null;
+  const pickTarget = (ev) => { host.style.setProperty('display', 'none', 'important'); const e = document.elementFromPoint(ev.clientX, ev.clientY); host.style.removeProperty('display'); return e; };
+  const highlight = (e) => { if (!e) { box.style.display = 'none'; return; } const r = e.getBoundingClientRect(); Object.assign(box.style, { display: 'block', left: r.left - 2 + 'px', top: r.top - 2 + 'px', width: r.width + 4 + 'px', height: r.height + 4 + 'px' }); };
+  // A control, or else the smallest element under the pointer (the text a check is about).
+  const pickable = (node) => { const c = control(node); return actionable(c) ? c : node && node.nodeType === 1 ? node : c; };
+  const startPick = (purpose) => { picking = { purpose }; mount(); say([[1, 'Pick an element'], [0, purpose === 'assert' ? ' to check' : purpose === 'variable' ? ' whose text to keep' : ' to wait for'], [0, ' · Esc cancels']], 0); };
+  const endPick = () => { picking = null; highlight(null); tip.style.display = 'none'; };
+  // Check, Variable, and Wait for start picking here at once: the next click is the pick, however soon it comes.
+  const picks = (cmd) => { if (['assert', 'variable', 'wait'].includes(cmd)) startPick(cmd); };
+  const swallow = (ev) => { if (!picking || !ev.isTrusted || ours(ev)) return false; ev.preventDefault(); ev.stopImmediatePropagation(); return true; };
+  for (const type of ['pointerdown', 'mousedown', 'pointerup', 'mouseup', 'dblclick', 'contextmenu']) window.addEventListener(type, swallow, true);
+  window.addEventListener('mousemove', (ev) => { if (picking) highlight(pickable(pickTarget(ev))); }, true);
+
+  // ---- hover menus: the trigger the pointer went over before a menu item showed ---------------------------------
+  const TRIGGER = 'a, button, [role=button], [role=menuitem], [aria-haspopup], [aria-expanded], summary';
+  const MENU = '[role=menu], [role=menubar] [role=menu], [role=listbox], ul ul, .dropdown-menu, .submenu, .sub-menu, [class*="dropdown"], [class*="submenu"], [class*="flyout"], [class*="mega"]';
+  const revealed = [];
+  let hovered = null;
+  window.addEventListener('mouseover', (ev) => {
+    if (!ev.isTrusted || picking || ours(ev)) return;
+    const t = ev.target.closest && ev.target.closest(TRIGGER);
+    if (t && (!hovered || t !== hovered.el)) hovered = { el: t, at: Date.now() };
+  }, true);
+  new MutationObserver((list) => {
+    if (!hovered || Date.now() - hovered.at > 1500) return;
+    for (const m of list) {
+      const n = m.type === 'childList' ? [...m.addedNodes].find((x) => x.nodeType === 1) : m.target;
+      if (n && n.nodeType === 1 && !n.contains(hovered.el) && n !== host) revealed.push({ by: hovered.el, root: n, at: Date.now() });
+    }
+    if (revealed.length > 50) revealed.splice(0, revealed.length - 50);
+  }).observe(document, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class', 'hidden', 'aria-hidden', 'aria-expanded', 'open'] });
+  const hoverFor = (c) => {
+    for (let i = revealed.length - 1; i >= 0; i--) {
+      const r = revealed[i];
+      if (r.root.contains(c) && r.by !== c && !r.by.contains(c) && r.by.isConnected && Date.now() - r.at < 60000) return r.by;
+    }
+    for (let e = c.parentElement, i = 0; e && e !== document.body && i < 8; e = e.parentElement, i++) {
+      if (!e.matches(MENU)) continue;
+      const owner = e.parentElement;
+      if (!owner || !owner.matches(':hover')) continue;
+      const trig = [...owner.children].find((x) => x !== e && !x.contains(c) && (x.matches(TRIGGER) || (x.querySelector && x.querySelector('a, button'))));
+      if (trig) return trig.matches(TRIGGER) ? trig : trig.querySelector('a, button');
+    }
+    return null;
+  };
+
+  // ---- typing: one fill with the field's final text when the tester moves on -------------------------------------
+  let dirty = null;
+  const flush = () => {
+    const e = dirty;
+    dirty = null;
+    if (!e) return;
+    const pw = isPassword(e);
+    send({ kind: 'fill', ...describeEl(e), password: pw, value: pw ? null : (e.isContentEditable ? norm(e.innerText) : e.value) });
+  };
+  window.addEventListener('input', (ev) => {
+    if (!ev.isTrusted || picking || ours(ev) || paused) return;
+    const e = ev.target.isContentEditable ? editableRoot(ev.target) : ev.target;
+    if (!isField(e)) return;
+    if (dirty && dirty !== e) flush();
+    dirty = e;
+  }, true);
+  window.addEventListener('focusout', (ev) => { if (dirty && ev.target === dirty) flush(); }, true);
+  window.addEventListener('pagehide', flush, true);
+  window.addEventListener('submit', (ev) => { if (ev.isTrusted !== false) flush(); }, true);
+
+  window.addEventListener('change', (ev) => {
+    if (!ev.isTrusted || picking || ours(ev) || paused) return;
+    const e = ev.target;
+    if (e.tagName === 'SELECT') { flush(); send({ kind: 'select', ...describeEl(e), text: shown(e) }); return; }
+    // The files' paths are read by ForgeQE through the DevTools protocol: the page itself only sees their names.
+    if (e.tagName === 'INPUT' && (e.getAttribute('type') || '').toLowerCase() === 'file') { send({ kind: 'upload', ...describeEl(e), count: e.files ? e.files.length : 0 }); return; }
+    if (dirty === e) flush();
+  }, true);
+
+  let lastLabel = null;
+  window.addEventListener('click', (ev) => {
+    if (!ev.isTrusted || ours(ev)) return;
+    if (picking) {
+      ev.preventDefault(); ev.stopImmediatePropagation();
+      const e = pickable(pickTarget(ev));
+      const purpose = picking.purpose;
+      endPick();
+      if (!e) return;
+      send({ kind: 'pick', purpose, ...describeEl(e), text: shown(e), password: isPassword(e), checked: 'checked' in e ? !!e.checked : null, field: e.tagName === 'INPUT' || e.tagName === 'TEXTAREA' || e.tagName === 'SELECT' });
+      return;
+    }
+    if (paused) return;
+    const c = control(ev.target);
+    if (!c || c.tagName === 'OPTION' || c.tagName === 'SELECT') return;
+    // A click on a label also clicks its control: one step.
+    if (lastLabel && lastLabel.control === c && Date.now() - lastLabel.at < 100) return;
+    if (c.tagName === 'LABEL') lastLabel = { control: c.control, at: Date.now() };
+    if (dirty && dirty !== c) flush();
+    const h = hoverFor(c);
+    send({ kind: 'click', ...describeEl(c), field: isField(c), ...(h ? { hover: describeEl(h) } : {}) });
+  }, true);
+  window.addEventListener('dblclick', (ev) => {
+    if (!ev.isTrusted || picking || ours(ev) || paused) return;
+    const c = control(ev.target);
+    if (c && !isField(c)) send({ kind: 'dblclick', ...describeEl(c) });
+  }, true);
+  window.addEventListener('dragstart', (ev) => { if (ev.isTrusted && !paused && !picking && !ours(ev)) send({ kind: 'unsupported', action: 'drag', reason: 'drag and drop is not recorded yet; add it in the test' }); }, true);
+
+  // ---- keys: the leader key and its letter, then Enter, Escape, and chords ----------------------------------------
+  let leader = 0;
+  const L = CFG.leader;
+  const isLeader = (ev) => ev.code === L.code && !!ev.ctrlKey === !!L.ctrl && !!ev.shiftKey === !!L.shift && !!ev.altKey === !!L.alt && !!ev.metaKey === !!L.meta;
+  // The leader key, or the letter after it: handled (and kept from the page) wherever the focus is.
+  const leaderKey = (ev) => {
+    if (isLeader(ev)) {
+      ev.preventDefault(); ev.stopImmediatePropagation();
+      leader = Date.now();
+      const parts = [];
+      for (const [k, , label] of CFG.commands) parts.push([1, ' ' + k.toUpperCase() + ' '], [0, label + ' ·']);
+      say(parts, 3000);
+      return true;
+    }
+    if (leader && Date.now() - leader < 3000 && !['Shift', 'Control', 'Alt', 'Meta'].includes(ev.key)) {
+      leader = 0;
+      ev.preventDefault(); ev.stopImmediatePropagation();
+      tip.style.display = 'none';
+      const hit = CFG.commands.find(([k]) => k === ev.key.toLowerCase());
+      if (hit) { if (dirty) flush(); picks(hit[1]); send({ kind: 'command', cmd: hit[1] }); }
+      return true;
+    }
+    return false;
+  };
+  window.addEventListener('keydown', (ev) => {
+    if (!ev.isTrusted || ours(ev)) return;
+    if (leaderKey(ev)) return;
+    if (picking) {
+      if (ev.key === 'Escape') { ev.preventDefault(); ev.stopImmediatePropagation(); endPick(); send({ kind: 'pick_cancel' }); }
+      return;
+    }
+    if (paused || ['Shift', 'Control', 'Alt', 'Meta'].includes(ev.key)) return;
+    const e = ev.target && ev.target.nodeType === 1 ? (ev.target.isContentEditable ? editableRoot(ev.target) : ev.target) : null;
+    const inField = isField(e);
+    const mods = [ev.ctrlKey && 'Control', ev.altKey && 'Alt', ev.metaKey && 'Meta', ev.shiftKey && ev.key.length > 1 && 'Shift'].filter(Boolean);
+    const key = ev.key === ' ' ? 'Space' : ev.key.length === 1 ? ev.key.toLowerCase() : ev.key;
+    if (inField && !mods.length && ['Tab'].includes(key)) return;
+    const chord = [...mods, key].join('+');
+    if (inField && !mods.length && !['Enter', 'Escape', 'ArrowDown', 'ArrowUp'].includes(key)) return;
+    if (inField && mods.length && ['Control', 'Meta'].some((m) => mods.includes(m)) && 'acvxzy'.includes(key)) return;
+    if (!inField && !mods.length && !['Enter', 'Escape'].includes(key)) return;
+    // Enter on a focused button or link clicks it, and the click is the step.
+    if (!inField && !mods.length && key === 'Enter' && actionable(e)) return;
+    if (dirty) flush();
+    send({ kind: 'press', keys: chord, in_field: inField, autocomplete: autocomplete(e) });
+  }, true);
+
+  globalThis.__fqeRec = {
+    el: elAt,
+    pick: (purpose) => startPick(purpose),
+    cancelPick: () => endPick(),
+    flush,
+    render,
+    log,
+    say: (t, ms) => say([[0, String(t)]], ms === undefined ? 2600 : ms),
+    focusChat: () => { ui.collapsed = false; place(); text.focus(); },
+    // How many visible elements a pattern locator finds: by role and an accessible name matching `source`, or by text.
+    countPattern: (role, source) => {
+      let rx;
+      try { rx = new RegExp(source); } catch (e) { return -1; }
+      if (role) return [...document.querySelectorAll(ROLE_SEL)].filter((x) => visible(x) && (x.getAttribute('role') || implicitRole(x)) === role && rx.test(accName(x))).length;
+      return [...document.querySelectorAll('body *')].filter((x) => visible(x) && !host.contains(x) && rx.test(norm(x.textContent)) && ![...x.children].some((c) => rx.test(norm(c.textContent)))).length;
+    },
+    // Where a control of the panel is on screen (tests click it as a person would).
+    box: (sel) => { const e = root.querySelector(sel); if (!e) return null; const r = e.getBoundingClientRect(); return [r.left + r.width / 2, r.top + r.height / 2]; },
+  };
+  if (document.documentElement) mount(); else document.addEventListener('DOMContentLoaded', mount, { once: true });
+  send({ kind: 'ready', url: location.href });
+})()"""
+
+
+def recorder_js(binding: str, kept: Any, *, leader: Dict[str, Any]) -> str:
+    config = {"binding": binding, "kept": list(kept), "leader": leader, "commands": [list(c) for c in COMMAND_KEYS]}
+    return RECORDER_JS.replace("__CONFIG__", json.dumps(config))

package/reporters/playwright.mjs

@@ -0,0 +1,83 @@
+// ForgeQE reporter for Playwright. After each run (npx playwright test, the VS Code test runner, CI) it writes the
+// results, with each failure's error, screenshot and trace, to <outputDir>/forgeqe-results.json and runs
+// `forgeqe report` on it, which writes the HTML report. `forgeqe report setup` copies this file into the repository;
+// it has no dependencies. FORGEQE_REPORT=0 turns it off; FORGEQE_BIN names the forgeqe command when it is not on PATH.
+import { spawnSync } from "node:child_process"
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g
+const clean = (s) => String(s || "").replace(ANSI, "")
+
+// cmd.exe joins the arguments of a shell: true spawn unquoted: each is quoted (as winQuote in ForgeQE's src/update.ts).
+const winQuote = (a) => (/[\s&|<>^()%!"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a)
+
+export default class ForgeQEReporter {
+  constructor() {
+    this.tests = new Map()
+  }
+
+  printsToStdio() {
+    return false
+  }
+
+  onBegin(config) {
+    this.config = config
+    this.started = new Date()
+  }
+
+  onTestEnd(test, result) {
+    const seen = this.tests.get(test.id) || { test, results: [] }
+    seen.results.push(result)
+    this.tests.set(test.id, seen)
+  }
+
+  onEnd(result) {
+    if (process.env.FORGEQE_REPORT === "0" || !this.tests.size) return
+    const multi = this.config.projects.length > 1
+    const tests = [...this.tests.values()].map(({ test, results }) => entry(test, results, multi))
+    const outputDir = this.config.projects[0]?.outputDir || path.join(process.cwd(), "test-results")
+    const file = path.join(outputDir, "forgeqe-results.json")
+    mkdirSync(outputDir, { recursive: true })
+    const doc = { format: "forgeqe-results", version: 1, framework: "Playwright", startedAt: this.started.toISOString(), ms: Math.round(result.duration), command: `playwright ${process.argv.slice(2).join(" ")}`.trim(), tests }
+    writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`)
+    const cwd = this.config.configFile ? path.dirname(this.config.configFile) : process.cwd()
+    report(file, cwd)
+  }
+}
+
+function entry(test, results, multi) {
+  const outcome = test.outcome()
+  const last = results[results.length - 1]
+  const failing = results.find((r) => r.status !== "passed" && r.status !== "skipped")
+  const [, project, ...rest] = test.titlePath()
+  const name = `${multi && project ? `[${project}] ` : ""}${rest.join(" › ")}`
+  const status = outcome === "skipped" ? "skipped" : outcome === "unexpected" ? "failed" : "passed"
+  const out = { name, status, seconds: Math.round((last?.duration || 0) / 10) / 100, file: path.relative(process.cwd(), test.location.file) }
+  if (outcome === "flaky") out.flaky = true
+  if (failing && status !== "skipped") {
+    const errors = failing.errors?.length ? failing.errors : failing.error ? [failing.error] : []
+    const message = clean(errors[0]?.message).split("\n").find((l) => l.trim())
+    if (message) out.message = message.trim().slice(0, 300)
+    const details = errors.map((e) => clean(e.stack || e.message)).join("\n\n").trim()
+    if (details) out.details = details
+    out.attachments = failing.attachments.filter((a) => a.path).map((a) => ({ name: a.name, path: a.path, contentType: a.contentType }))
+  }
+  return out
+}
+
+function report(file, cwd) {
+  const bin = process.env.FORGEQE_BIN || "forgeqe"
+  const windows = process.platform === "win32"
+  const args = ["report", file]
+  const run = spawnSync(windows ? winQuote(bin) : bin, windows ? args.map(winQuote) : args, { cwd, encoding: "utf8", shell: windows, timeout: 180_000 })
+  // forgeqe report exits 1 when a test failed: that is a report, not an error. Without a Report line it did not run
+  // (on Windows a missing command is cmd.exe's exit 1, not ENOENT).
+  const line = run.status !== null && run.status <= 1 ? clean(run.stdout).split("\n").find((l) => l.startsWith("Report")) : undefined
+  if (line) {
+    console.log(`\nForgeQE ${line.replace(/^Report\s+/, "report: ")}`)
+    return
+  }
+  const why = run.error?.code === "ENOENT" ? "forgeqe is not on PATH" : clean(run.stderr).trim().split("\n").pop() || "it did not finish"
+  console.log(`\nForgeQE: no report (${why}). Build it with: forgeqe report ${path.relative(cwd, file)}`)
+}