halo-agent 1.1.0

package/filler.js

@@ -0,0 +1,987 @@
+'use strict';
+
+/**
+ * ATS-specific form fill strategies.
+ * All filling goes through the user's real Chrome via CDP — no fake browser.
+ */
+
+const TYPING_SPEEDS = { slow: 80, normal: 40, fast: 15 };
+
+// Randomize delay slightly to look human
+function jitter(base) {
+  return Math.floor(base * (0.7 + Math.random() * 0.6));
+}
+
+/**
+ * Set a form field value in a React/Vue/Angular aware way.
+ * Fires the full event sequence that frameworks listen for.
+ */
+async function setFieldValue(page, selector, value) {
+  try {
+    await page.locator(selector).first().waitFor({ timeout: 3000 });
+    await page.evaluate(({ sel, val }) => {
+      const el = document.querySelector(sel);
+      if (!el) return;
+      el.focus();
+      // React's synthetic event system requires using the native setter
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
+        || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+      if (nativeInputValueSetter) nativeInputValueSetter.call(el, val);
+      el.dispatchEvent(new Event('focus', { bubbles: true }));
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      el.dispatchEvent(new Event('blur', { bubbles: true }));
+    }, { sel: selector, val: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Set a field value by Playwright element handle (used after semantic matching).
+ */
+async function setFieldValueByHandle(page, elementHandle, value) {
+  try {
+    await page.evaluate(({ val }) => {
+      const el = arguments[0]; // handled via elementHandle approach below
+    }, { val: value });
+    // Use evaluate with the handle directly
+    await elementHandle.evaluate((el, val) => {
+      el.focus();
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
+        || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+      if (nativeInputValueSetter) nativeInputValueSetter.call(el, val);
+      el.dispatchEvent(new Event('focus', { bubbles: true }));
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      el.dispatchEvent(new Event('blur', { bubbles: true }));
+    }, value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Type text character by character (for textareas like cover letters).
+ * Much more human-looking than setting value atomically.
+ */
+async function typeFieldValue(page, selector, value, speed = 'normal') {
+  const delay = TYPING_SPEEDS[speed] || 40;
+  try {
+    const el = page.locator(selector).first();
+    await el.waitFor({ timeout: 3000 });
+    await el.click();
+    await el.fill(''); // clear first
+    await page.keyboard.type(value, { delay: jitter(delay) });
+    await el.dispatchEvent('change');
+    return true;
+  } catch {
+    // Fallback to setFieldValue
+    return setFieldValue(page, selector, value);
+  }
+}
+
+/**
+ * Fill a native <select> dropdown.
+ */
+async function setSelectValue(page, selector, value) {
+  try {
+    await page.locator(selector).first().selectOption({ label: value }).catch(() =>
+      page.locator(selector).first().selectOption({ value })
+    );
+    return true;
+  } catch {
+    // Try clicking the option via custom React dropdown
+    return clickDropdownOption(page, selector, value);
+  }
+}
+
+/**
+ * For custom React dropdowns: click trigger, then click matching option.
+ */
+async function clickDropdownOption(page, triggerSelector, optionText) {
+  try {
+    await page.locator(triggerSelector).first().click();
+    await page.waitForTimeout(400);
+    // Look for option by text in any listbox or menu element
+    const optionEl = page.getByRole('option', { name: optionText }).or(
+      page.locator(`[role="menuitem"]:has-text("${optionText}")`).or(
+        page.locator(`li:has-text("${optionText}")`)
+      )
+    ).first();
+    await optionEl.waitFor({ timeout: 2000 });
+    await optionEl.click();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Click a radio button by group name and option label text.
+ */
+async function selectRadioOption(page, groupName, value) {
+  try {
+    // Try to find a radio input with matching name and value
+    const byValue = page.locator(`input[type="radio"][name="${groupName}"][value="${value}" i]`).first();
+    if (await byValue.isVisible({ timeout: 500 }).catch(() => false)) {
+      await byValue.click();
+      return true;
+    }
+
+    // Fall back: find all radios in the group, click the one whose label matches
+    const radios = await page.locator(`input[type="radio"][name="${groupName}"]`).all();
+    for (const radio of radios) {
+      const label = await radio.evaluate(el => {
+        // Check label element
+        if (el.id) {
+          const lbl = document.querySelector(`label[for="${el.id}"]`);
+          if (lbl) return lbl.textContent.trim();
+        }
+        // Walk up to find label text
+        let p = el.parentElement;
+        let depth = 0;
+        while (p && depth < 4) {
+          const lbl = p.querySelector('label, span, div');
+          if (lbl && lbl !== el) {
+            const t = lbl.textContent.trim();
+            if (t.length > 0 && t.length < 80) return t;
+          }
+          p = p.parentElement;
+          depth++;
+        }
+        return el.value || '';
+      });
+      if (label.toLowerCase().includes(value.toLowerCase()) || value.toLowerCase().includes(label.toLowerCase())) {
+        await radio.click();
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Click a checkbox by its label or value.
+ */
+async function clickCheckbox(page, label, value) {
+  try {
+    const checkboxes = await page.locator('input[type="checkbox"]').all();
+    for (const cb of checkboxes) {
+      const cbLabel = await cb.evaluate(el => {
+        if (el.id) {
+          const lbl = document.querySelector(`label[for="${el.id}"]`);
+          if (lbl) return lbl.textContent.trim();
+        }
+        let p = el.parentElement;
+        let depth = 0;
+        while (p && depth < 4) {
+          const t = p.textContent.trim();
+          if (t.length > 0 && t.length < 100) return t;
+          p = p.parentElement;
+          depth++;
+        }
+        return el.value || '';
+      });
+
+      const target = (label || value || '').toLowerCase();
+      if (target && cbLabel.toLowerCase().includes(target)) {
+        const isChecked = await cb.isChecked();
+        if (!isChecked) await cb.click();
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Upload a resume PDF using Playwright's fileChooser interception.
+ * Works even when the file input is hidden behind a custom button.
+ */
+async function uploadFile(page, triggerSelector, filePath) {
+  try {
+    const [fileChooser] = await Promise.all([
+      page.waitForFileChooser({ timeout: 5000 }),
+      page.locator(triggerSelector).first().click().catch(() => {}),
+    ]);
+    await fileChooser.setFiles(filePath);
+    return true;
+  } catch {
+    // Fallback: direct setInputFiles on any file input
+    try {
+      await page.locator('input[type="file"]').first().setInputFiles(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Universal field filler — given a Playwright locator and a string value,
+ * detects the field type and applies the right fill strategy.
+ *
+ * Handles all field types that appear in real job applications:
+ *   - Native <select> dropdown
+ *   - Custom dropdown (React Select, Ashby combobox — role="combobox" or role="listbox")
+ *   - Radio group (native input[type=radio] or custom role="radio")
+ *   - Checkbox (native or custom role="checkbox")
+ *   - Yes/No button group (styled buttons acting as a radio group)
+ *   - Textarea / long text
+ *   - Short text input (text, email, tel, number, url)
+ *   - Date input
+ *
+ * Returns true if fill succeeded.
+ */
+async function fillLocator(page, locator, value, label) {
+  if (!value) return false;
+
+  try {
+    // Inspect the element to determine field type
+    const meta = await locator.evaluate(el => ({
+      tag: el.tagName.toLowerCase(),
+      type: (el.type || '').toLowerCase(),
+      role: (el.getAttribute('role') || '').toLowerCase(),
+      isContentEditable: el.isContentEditable,
+      hasOptions: el.tagName === 'SELECT',
+      optionCount: el.tagName === 'SELECT' ? el.options.length : 0,
+    })).catch(() => ({ tag: 'input', type: 'text', role: '', isContentEditable: false, hasOptions: false, optionCount: 0 }));
+
+    // ── Native <select> ──
+    if (meta.tag === 'select' || meta.hasOptions) {
+      const opts = await locator.evaluate(e => Array.from(e.options).map(o => ({ v: o.value, t: o.text.trim() }))).catch(() => []);
+      // 1. Exact label match
+      let ok = await locator.selectOption({ label: value }).then(() => true).catch(() => false);
+      // 2. Exact value match
+      if (!ok) ok = await locator.selectOption({ value }).then(() => true).catch(() => false);
+      // 3. Case-insensitive label match
+      if (!ok) {
+        const match = opts.find(o => o.t.toLowerCase() === value.toLowerCase());
+        if (match) ok = await locator.selectOption(match.v).then(() => true).catch(() => false);
+      }
+      // 4. Fuzzy: value is substring of option text or vice versa
+      if (!ok) {
+        const fuzzy = opts.find(o =>
+          o.t.toLowerCase().includes(value.toLowerCase()) ||
+          value.toLowerCase().includes(o.t.toLowerCase())
+        );
+        if (fuzzy) ok = await locator.selectOption(fuzzy.v).then(() => true).catch(() => false);
+      }
+      return ok;
+    }
+
+    // ── Custom dropdown / combobox (React Select, Ashby, Lever custom selects) ──
+    if (meta.role === 'combobox' || meta.role === 'listbox' ||
+        meta.tag === 'div' || meta.tag === 'button') {
+      return await fillCustomDropdown(page, locator, value);
+    }
+
+    // ── Radio group (native) ──
+    if (meta.type === 'radio') {
+      // locator points to one radio — find its group and select by value
+      const groupName = await locator.evaluate(e => e.name).catch(() => '');
+      return await selectRadioOption(page, groupName, value);
+    }
+
+    // ── Checkbox (native) ──
+    if (meta.type === 'checkbox') {
+      const shouldCheck = /^(yes|true|1|on|agree|accept)$/i.test(value.trim());
+      const checked = await locator.isChecked().catch(() => false);
+      if (shouldCheck !== checked) await locator.click();
+      return true;
+    }
+
+    // ── Date input ──
+    if (meta.type === 'date') {
+      // Try to parse value into YYYY-MM-DD format
+      const parsed = parseDate(value);
+      return await locator.fill(parsed || value).then(() => true).catch(() => false);
+    }
+
+    // ── Number input ──
+    if (meta.type === 'number') {
+      const num = value.replace(/[^0-9.]/g, '');
+      return await locator.fill(num).then(() => {
+        return locator.dispatchEvent('change').then(() => true);
+      }).catch(() => false);
+    }
+
+    // ── contenteditable div (some ATS use these for rich text fields) ──
+    if (meta.isContentEditable) {
+      await locator.click();
+      await locator.evaluate(el => el.innerHTML = '');
+      await locator.type(value, { delay: 20 });
+      return true;
+    }
+
+    // ── Textarea / long text ──
+    if (meta.tag === 'textarea') {
+      await locator.fill(value);
+      await locator.dispatchEvent('input');
+      await locator.dispatchEvent('change');
+      return true;
+    }
+
+    // ── Default: short text input (text, email, tel, url, search, etc.) ──
+    return await setFieldValueByHandle(page, locator, value);
+
+  } catch (e) {
+    console.warn(`[filler] fillLocator error for "${label}": ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Fill a custom dropdown that is NOT a native <select>.
+ * Strategy: click trigger → wait for option list → find closest matching option → click it.
+ * Handles React Select, Ashby custom select, Lever, Greenhouse custom dropdowns.
+ */
+async function fillCustomDropdown(page, triggerLocator, value) {
+  try {
+    await triggerLocator.click();
+    await page.waitForTimeout(350);
+
+    // Look for an open listbox, menu, or option list
+    const optionSelectors = [
+      `[role="option"]:has-text("${value}")`,
+      `[role="menuitem"]:has-text("${value}")`,
+      `li:has-text("${value}")`,
+      `.Select-option:has-text("${value}")`,
+      `[class*="option"]:has-text("${value}")`,
+    ];
+
+    for (const sel of optionSelectors) {
+      try {
+        const opt = page.locator(sel).first();
+        if (await opt.isVisible({ timeout: 800 })) {
+          await opt.click();
+          return true;
+        }
+      } catch {}
+    }
+
+    // Fuzzy: get all visible options and find closest match
+    const allOptions = await page.locator('[role="option"], [role="menuitem"]').all();
+    let bestMatch = null;
+    let bestScore = 0;
+    for (const opt of allOptions) {
+      const text = (await opt.textContent().catch(() => '')).trim().toLowerCase();
+      const target = value.toLowerCase();
+      const score = text === target ? 1 :
+                    text.includes(target) ? 0.8 :
+                    target.includes(text) ? 0.7 : 0;
+      if (score > bestScore) { bestScore = score; bestMatch = opt; }
+    }
+    if (bestMatch && bestScore >= 0.7) {
+      await bestMatch.click();
+      return true;
+    }
+
+    // Nothing found — press Escape to close the dropdown
+    await page.keyboard.press('Escape');
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse a human date string into YYYY-MM-DD for date inputs.
+ */
+function parseDate(value) {
+  try {
+    const d = new Date(value);
+    if (isNaN(d.getTime())) return null;
+    return d.toISOString().split('T')[0];
+  } catch { return null; }
+}
+
+/**
+ * Find the best selector for a field given its label, id, name, or placeholder.
+ * Tries multiple strategies in order of reliability.
+ */
+function buildSelector(field) {
+  if (field.id) return `#${CSS.escape(field.id)}`;
+  if (field.name) return `[name="${field.name}"]`;
+  // Label-based
+  const label = (field.label || '').toLowerCase();
+  if (label) {
+    if (field.tag === 'textarea') return `textarea[placeholder*="${field.label}"], textarea[aria-label*="${field.label}"]`;
+    return `input[placeholder*="${field.label}"], input[aria-label*="${field.label}"]`;
+  }
+  return null;
+}
+
+// Escape CSS special chars for querySelector
+const CSS = { escape: (s) => s.replace(/([!"#$%&'()*+,.\/:;<=>?@\[\\\]^`{|}~])/g, '\\$1') };
+
+/**
+ * Extract all visible form fields from the current page via DOM walking.
+ * Uses the same 6-tier label extraction as the Chrome extension (content.js).
+ * Returns [{tag, type, id, name, label, value}] for all visible fields.
+ */
+async function extractPageFields(page) {
+  return page.evaluate(() => {
+    function getFieldLabel(el) {
+      // 1. Native <label for="..."> association
+      if (el.id) {
+        var lbl = document.querySelector('label[for="' + el.id + '"]');
+        if (lbl) return lbl.textContent.trim();
+      }
+      if (el.labels && el.labels[0]) return el.labels[0].textContent.trim();
+      // 2. aria-label / aria-labelledby
+      var ariaLabel = el.getAttribute('aria-label');
+      if (ariaLabel) return ariaLabel.trim();
+      var ariaLabelledBy = el.getAttribute('aria-labelledby');
+      if (ariaLabelledBy) {
+        var lblEl = document.getElementById(ariaLabelledBy);
+        if (lblEl) return lblEl.textContent.trim();
+      }
+      // 3. data-label / data-title
+      if (el.dataset && el.dataset.label) return el.dataset.label.trim();
+      if (el.dataset && el.dataset.title) return el.dataset.title.trim();
+      // 4. Immediately preceding sibling label/span/div
+      var prev = el.previousElementSibling;
+      while (prev) {
+        if (/LABEL|SPAN|DIV|P|LEGEND|H1|H2|H3|H4|H5/.test(prev.tagName)) {
+          var t = prev.textContent.trim();
+          if (t.length > 0 && t.length < 120) return t;
+        }
+        prev = prev.previousElementSibling;
+      }
+      // 5. Walk up DOM — find nearest container with a label/legend/heading
+      var parent = el.parentElement;
+      var depth = 0;
+      while (parent && depth < 6) {
+        var lbl2 = parent.querySelector('label, legend, [class*=label], [class*=title], [class*=question], [class*=heading]');
+        if (lbl2 && lbl2 !== el) {
+          var t2 = lbl2.textContent.trim();
+          if (t2.length > 0 && t2.length < 120) return t2;
+        }
+        parent = parent.parentElement;
+        depth++;
+      }
+      // 6. Placeholder / name fallback
+      return el.placeholder || el.name || el.id || '';
+    }
+
+    var fields = [];
+    document.querySelectorAll('input, textarea, select').forEach(function(el) {
+      if (el.type === 'hidden' || el.type === 'submit' || el.type === 'file' || el.type === 'button' || el.type === 'image') return;
+      if (!el.offsetParent && el.type !== 'radio' && el.type !== 'checkbox') return;
+
+      var label = getFieldLabel(el);
+      label = label.replace(/\s+/g, ' ').replace(/^\*\s*/, '').replace(/\s*\*$/, '').trim();
+
+      fields.push({
+        tag: el.tagName.toLowerCase(),
+        type: el.type || '',
+        id: el.id || '',
+        name: el.name || '',
+        label: label.slice(0, 200),
+        value: el.value || '',
+        // Build a unique data-fingerprint so we can locate this element after evaluate()
+        // We use a combo of id, name, and label for matching
+      });
+    });
+    return fields;
+  });
+}
+
+/**
+ * Compute Jaccard word-level similarity between two strings.
+ * Used for semantic field matching when exact selectors fail.
+ */
+function jaccardSimilarity(a, b) {
+  const normalize = s => s.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).filter(w => w.length > 2);
+  const setA = new Set(normalize(a));
+  const setB = new Set(normalize(b));
+  if (setA.size === 0 || setB.size === 0) return 0;
+  const intersection = [...setA].filter(w => setB.has(w)).length;
+  const union = new Set([...setA, ...setB]).size;
+  return intersection / union;
+}
+
+/**
+ * 3-tier semantic field finder.
+ * Tier 1: exact ID/name match
+ * Tier 2: aria-label/placeholder substring match
+ * Tier 3: full DOM walking label extraction with Jaccard similarity scoring
+ *
+ * Returns a Playwright Locator or null.
+ */
+async function semanticFindField(page, fieldAnswer) {
+  const { field_id, label } = fieldAnswer;
+
+  // Tier 1: exact ID or name match
+  if (field_id && !field_id.startsWith('sa_')) {
+    const escaped = CSS.escape(field_id);
+    try {
+      const el = page.locator(`#${escaped}, [name="${field_id}"]`).first();
+      if (await el.isVisible({ timeout: 500 })) return el;
+    } catch {}
+  }
+
+  // Tier 2: aria-label / placeholder substring match
+  if (label) {
+    const escapedLabel = label.replace(/['"]/g, '').trim();
+    if (escapedLabel) {
+      try {
+        const sel = `textarea[aria-label*="${escapedLabel}" i], input[aria-label*="${escapedLabel}" i], textarea[placeholder*="${escapedLabel}" i], input[placeholder*="${escapedLabel}" i], select[aria-label*="${escapedLabel}" i]`;
+        const el = page.locator(sel).first();
+        if (await el.isVisible({ timeout: 500 })) return el;
+      } catch {}
+    }
+  }
+
+  // Tier 3: full DOM walk + Jaccard similarity across all visible fields
+  if (label) {
+    try {
+      const pageFields = await extractPageFields(page);
+      let bestScore = 0;
+      let bestField = null;
+
+      for (const pf of pageFields) {
+        const score = jaccardSimilarity(label, pf.label);
+        if (score > bestScore) {
+          bestScore = score;
+          bestField = pf;
+        }
+      }
+
+      if (bestScore >= 0.4 && bestField) {
+        // Try to locate this element by its id/name/label combination
+        let locator = null;
+
+        if (bestField.id) {
+          try {
+            const escaped = CSS.escape(bestField.id);
+            const el = page.locator(`#${escaped}`).first();
+            if (await el.isVisible({ timeout: 300 })) locator = el;
+          } catch {}
+        }
+
+        if (!locator && bestField.name) {
+          try {
+            const el = page.locator(`[name="${bestField.name}"]`).first();
+            if (await el.isVisible({ timeout: 300 })) locator = el;
+          } catch {}
+        }
+
+        if (!locator && bestField.label) {
+          const escapedBest = bestField.label.replace(/['"]/g, '').trim();
+          if (escapedBest) {
+            try {
+              // Include select elements here — dropdowns matched via Tier3 Jaccard
+              const sel = `textarea[aria-label*="${escapedBest}" i], input[aria-label*="${escapedBest}" i], textarea[placeholder*="${escapedBest}" i], input[placeholder*="${escapedBest}" i], select[aria-label*="${escapedBest}" i]`;
+              const el = page.locator(sel).first();
+              if (await el.isVisible({ timeout: 300 })) locator = el;
+            } catch {}
+            // Final fallback: getByLabel for fields like Greenhouse dropdowns
+            if (!locator) {
+              try {
+                const el = page.getByLabel(new RegExp(escapedBest.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')).first();
+                if (await el.isVisible({ timeout: 300 })) locator = el;
+              } catch {}
+            }
+          }
+        }
+
+        if (locator) {
+          const confidence = bestScore >= 0.7 ? 'high' : 'medium';
+          console.log(`[filler] Tier3 match (${confidence}, score=${bestScore.toFixed(2)}): "${label}" -> "${bestField.label}"`);
+          return locator;
+        }
+      }
+    } catch (e) {
+      console.warn(`[filler] Tier3 DOM walk failed: ${e.message}`);
+    }
+  }
+
+  console.log(`[filler] unmatched: "${label}"`);
+  return null;
+}
+
+/**
+ * Fill all fields on the current page using per-ATS scanPage() strategy.
+ *
+ * Pass 1: scanPage() identifies every visible field and classifies it as profile/custom/eeo/file.
+ * Pass 2: resolveFieldValues() maps each field to a value from the AEP (profile or AI answers).
+ * Pass 3: Fields with value=null and source='needs_ai' are returned in result.needsAI so the
+ *         orchestrator can fetch AI answers and call fillFields again.
+ *
+ * Returns { filled, skipped, failed, needsAI: [{label, selector, tag, inputType}] }.
+ */
+async function fillFields(page, aep, options = {}) {
+  const speed = options.speed || 'normal';
+  const ctx = options.ctx || null;
+  const ats = options.ats || 'generic';
+  const delay = () => new Promise(r => setTimeout(r, jitter(100 + Math.random() * 150)));
+
+  let filled = 0, skipped = 0, failed = 0;
+  const needsAI = [];
+
+  // ── Pass 1: scan all visible fields using per-ATS logic ───────────────────
+  const { scanPage, resolveFieldValues } = require('./scanPage');
+  const scannedFields = await scanPage(page, ats).catch(() => []);
+
+  // ── Pass 2: resolve values from AEP ──────────────────────────────────────
+  const resolved = resolveFieldValues(scannedFields, aep);
+
+  // ── Pass 3: fill each field ───────────────────────────────────────────────
+  for (const { field, value, source } of resolved) {
+    // Skip if already answered on a previous page
+    const trackKey = field.label || field.selector;
+    if (ctx && trackKey && ctx.answeredFields.has(trackKey)) {
+      skipped++;
+      continue;
+    }
+
+    // File uploads — handled separately by uploadResume() in orchestrator
+    if (source === 'file_upload') continue;
+
+    // EEO / consent — skip silently (vision handles EEO, user handles consent)
+    if (source === 'skip') continue;
+
+    // No value and needs AI — collect for batch AI fetch
+    if (!value && source === 'needs_ai') {
+      if (field.label && field.label.length >= 8) {
+        needsAI.push({ label: field.label, selector: field.selector, tag: field.tag, inputType: field.inputType, iframeSelector: field.iframeSelector });
+      } else {
+        skipped++;
+      }
+      continue;
+    }
+
+    // No value for a profile field — missing from profile, skip
+    if (!value) { skipped++; continue; }
+
+    // Locate the element — use the scanner's selector first, then fall back to semantic finder
+    let locator = null;
+
+    // If the field is inside an iframe (iCIMS), use frameLocator
+    if (field.iframeSelector) {
+      try {
+        const frame = page.frameLocator(field.iframeSelector);
+        locator = frame.locator(field.selector).first();
+        const visible = await locator.isVisible({ timeout: 500 }).catch(() => false);
+        if (!visible) locator = null;
+      } catch {}
+    }
+
+    // Standard locator via scanner selector
+    if (!locator && field.selector) {
+      try {
+        const el = page.locator(field.selector).first();
+        const visible = await el.isVisible({ timeout: 500 }).catch(() => false);
+        if (visible) locator = el;
+      } catch {}
+    }
+
+    // Fallback: semantic finder via label text
+    if (!locator && field.label) {
+      locator = await semanticFindField(page, { field_id: field.id || field.name, label: field.label }).catch(() => null);
+    }
+
+    if (!locator) { skipped++; continue; }
+
+    // Special case: cover letter — type character by character
+    if (field.category === 'cover_letter' && field.tag === 'textarea') {
+      try {
+        await locator.click();
+        await locator.fill('');
+        await page.keyboard.type(value, { delay: jitter(TYPING_SPEEDS[speed] || 40) });
+        await locator.dispatchEvent('change');
+        filled++;
+        if (ctx && trackKey) ctx.answeredFields.set(trackKey, { value, pageIndex: ctx.currentPageIndex, source });
+        await delay();
+      } catch { failed++; }
+      continue;
+    }
+
+    // Radio group — use name-based selector
+    if (field.inputType === 'radio') {
+      const ok = await selectRadioOption(page, field.name, value);
+      if (ok) {
+        filled++;
+        if (ctx && trackKey) ctx.answeredFields.set(trackKey, { value, pageIndex: ctx.currentPageIndex, source });
+        await delay();
+      } else {
+        // Try clicking the locator directly (custom styled radio)
+        const ok2 = await fillLocator(page, locator, value, field.label);
+        if (ok2) { filled++; if (ctx && trackKey) ctx.answeredFields.set(trackKey, { value, pageIndex: ctx.currentPageIndex, source }); await delay(); }
+        else { skipped++; }
+      }
+      continue;
+    }
+
+    // Checkbox
+    if (field.inputType === 'checkbox') {
+      const shouldCheck = /^(yes|true|1|on|agree|accept)$/i.test(value.trim());
+      try {
+        const checked = await locator.isChecked().catch(() => false);
+        if (shouldCheck !== checked) { await locator.click(); }
+        filled++;
+        if (ctx && trackKey) ctx.answeredFields.set(trackKey, { value, pageIndex: ctx.currentPageIndex, source });
+        await delay();
+      } catch { skipped++; }
+      continue;
+    }
+
+    // All other types — use universal fillLocator
+    try {
+      const ok = await fillLocator(page, locator, value, field.label);
+      if (ok) {
+        filled++;
+        if (ctx && trackKey) ctx.answeredFields.set(trackKey, { value, pageIndex: ctx.currentPageIndex, source });
+        await delay();
+      } else { failed++; }
+    } catch { failed++; }
+  }
+
+  // ── Legacy fallback: also run old profile map + semantic matcher ──────────
+  // This catches any fields that scanPage missed (e.g. unusual ATS not yet modeled).
+  const profileMap = buildProfileMap(aep.profile_fill);
+  for (const [labelPattern, value] of Object.entries(profileMap)) {
+    if (!value) continue;
+    if (ctx && ctx.answeredFields.has(labelPattern)) continue;
+    let didFill = false;
+
+    try {
+      const sel = buildProfileSelector(labelPattern);
+      if (sel) {
+        const el = page.locator(sel).first();
+        if (await el.isVisible().catch(() => false)) {
+          const ok = await fillLocator(page, el, value, labelPattern);
+          if (ok) { didFill = true; filled++; }
+        }
+      }
+    } catch {}
+
+    if (!didFill) {
+      for (const part of labelPattern.split('|').map(p => p.trim())) {
+        if (didFill) break;
+        try {
+          const ok = await fillProfileFieldByLabel(page, part, value, speed);
+          if (ok) { didFill = true; filled++; }
+        } catch {}
+      }
+    }
+
+    if (didFill && ctx) {
+      ctx.answeredFields.set(labelPattern, { value, pageIndex: ctx.currentPageIndex, source: 'profile' });
+    }
+  }
+
+  return { filled, skipped, failed, needsAI };
+}
+
+/**
+ * Build a CSS selector from a label string for textareas and inputs.
+ */
+function buildLabelSelector(label) {
+  if (!label) return null;
+  const escaped = label.replace(/['"]/g, '').trim();
+  return `textarea[aria-label*="${escaped}" i], input[aria-label*="${escaped}" i], textarea[placeholder*="${escaped}" i], input[placeholder*="${escaped}" i]`;
+}
+
+/**
+ * Map profile_fill keys to CSS selector patterns.
+ */
+function buildProfileMap(profile) {
+  if (!profile) return {};
+  const phone = profile.phone || '';
+  const email = profile.email || '';
+  const fullName = [profile.first_name, profile.last_name].filter(Boolean).join(' ');
+  return {
+    // Keys are pipe-separated substrings matched against label text (case-insensitive)
+    // Full name (Lever, Ashby) — must come before first/last to avoid partial matches
+    'full name|full_name|your name|^name$': fullName,
+    'first_name|firstname|first-name|first name|given name': profile.first_name,
+    'last_name|lastname|last-name|last name|surname|family name': profile.last_name,
+    'preferred|goes by': profile.preferred_name || profile.first_name || '',
+    'email': email,
+    'phone|mobile|telephone|cell': phone,
+    'linkedin': profile.linkedin,
+    'github': profile.github,
+    'twitter': profile.twitter || '',
+    'portfolio|personal site|personal url': profile.portfolio || '',
+    'website': profile.portfolio || profile.website || '',
+    'school|university|college|institution': profile.school || '',
+    'degree|education|qualification': profile.degree || '',
+    'gpa|grade point': profile.gpa || '',
+    'address|street': profile.address || '',
+    'city': profile.city || '',
+    'state|province|region': profile.state || '',
+    'zip|postal': profile.zip || '',
+    'country': profile.country || 'United States',
+    'location|current location': profile.city || profile.location || '',
+    'current company|current employer|organization|employer': profile.current_company || '',
+    'desired salary|expected salary|salary expectation': profile.desired_salary || '',
+    'start date|available|availability': profile.start_date || 'Immediately',
+    // Combined phone+email (Ashby contact field pattern)
+    'phone.*email|email.*phone|contact.*reach|reach.*contact': phone && email ? `${phone} | ${email}` : (phone || email),
+  };
+}
+
+/**
+ * Fill a single profile field using label-text matching via DOM walk.
+ * More reliable than attribute-only selectors for Greenhouse/Ashby where
+ * inputs have no aria-label but have a visible <label> element.
+ */
+async function fillProfileFieldByLabel(page, labelText, value, speed) {
+  if (!value) return false;
+  try {
+    const el = page.getByLabel(new RegExp(labelText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')).first();
+    if (!await el.isVisible({ timeout: 600 }).catch(() => false)) return false;
+    // Route through universal fillLocator — handles all field types correctly
+    return await fillLocator(page, el, value, labelText);
+  } catch { return false; }
+}
+
+function buildProfileSelector(labelPattern) {
+  // Build selectors for both input and select elements using id/name/aria-label/placeholder
+  const parts = labelPattern.split('|').map(p => p.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const selectors = [];
+  for (const p of parts) {
+    // Match on id, name, aria-label, placeholder for both input and select
+    selectors.push(
+      `input[name*="${p}" i]`, `input[id*="${p}" i]`,
+      `input[aria-label*="${p}" i]`, `input[placeholder*="${p}" i]`,
+      `select[name*="${p}" i]`, `select[id*="${p}" i]`, `select[aria-label*="${p}" i]`,
+      `textarea[name*="${p}" i]`, `textarea[id*="${p}" i]`,
+      `textarea[aria-label*="${p}" i]`, `textarea[placeholder*="${p}" i]`,
+    );
+  }
+  return selectors.join(', ');
+}
+
+/**
+ * Find the "Next" or "Continue" button on a multi-page form.
+ */
+async function findNextButton(page) {
+  const selectors = [
+    // Workday-specific
+    '[data-automation-id="bottom-navigation-next-button"]',
+    '[data-automation-id="next-button"]',
+    // Generic
+    'button:has-text("Next")',
+    'button:has-text("Continue")',
+    'button:has-text("Save and Continue")',
+    'button:has-text("Save & Continue")',
+    'button[type="submit"]:has-text("Next")',
+    '[data-testid="next-button"]',
+    '[aria-label="Next"]',
+    '[aria-label="Continue"]',
+  ];
+  for (const sel of selectors) {
+    try {
+      const el = page.locator(sel).first();
+      if (await el.isVisible({ timeout: 500 })) {
+        const text = (await el.textContent().catch(() => '')).toLowerCase().trim();
+        if (text.includes('submit')) continue; // don't treat Submit as Next
+        return el;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * Find the final "Submit" button on a review/submit page.
+ * Tries many patterns to handle SmartRecruiters, Greenhouse, Ashby, Lever, Workday, etc.
+ */
+async function findSubmitButton(page) {
+  // Ordered from most specific to most generic
+  const selectors = [
+    // Workday-specific
+    '[data-automation-id="bottom-navigation-next-button"]:has-text("Submit")',
+    '[data-automation-id="submit-button"]',
+    '[data-automation-id="review-submit-button"]',
+    // Generic
+    'button:has-text("Submit application")',
+    'button:has-text("Submit Application")',
+    'button:has-text("Submit My Application")',
+    'button:has-text("Submit")',
+    'button:has-text("Apply Now")',
+    'button:has-text("Send Application")',
+    'button:has-text("Complete Application")',
+    'button:has-text("Finish")',
+    'button:has-text("Review and Submit")',
+    '[data-testid="submit-button"]',
+    '[data-testid="apply-button"]',
+    '[aria-label*="submit" i]',
+    'input[type="submit"]',
+    // Generic: any submit-type button that isn't navigation
+    'button[type="submit"]',
+    'form button:last-of-type',
+  ];
+  for (const sel of selectors) {
+    try {
+      const el = page.locator(sel).first();
+      if (await el.isVisible({ timeout: 500 })) {
+        // Skip if it looks like a Next/Continue button
+        const text = (await el.textContent().catch(() => '')).toLowerCase().trim();
+        if (text.includes('next') || text.includes('continue') || text.includes('save and') || text.includes('save &')) continue;
+        return el;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * Wait for the DOM's form field count to stabilize (smart replacement for waitForTimeout).
+ * Stops polling as soon as the count has been stable for 2 consecutive 300ms intervals.
+ */
+async function waitForStableDOM(page, maxWait = 4000) {
+  const start = Date.now();
+  let lastCount = -1;
+  let stableCount = 0;
+
+  while (Date.now() - start < maxWait) {
+    await page.waitForTimeout(300);
+    const count = await page.evaluate(() =>
+      document.querySelectorAll('input:not([type=hidden]):not([type=submit]), textarea, select').length
+    ).catch(() => 0);
+
+    if (count === lastCount && count > 0) {
+      stableCount++;
+      if (stableCount >= 2) break; // stable for 600ms — good enough
+    } else {
+      stableCount = 0;
+    }
+    lastCount = count;
+  }
+}
+
+/**
+ * Snapshot all current visible field labels on the page.
+ * Used by orchestrator to detect conditional fields that appear after clicking Next.
+ */
+async function snapshotFieldLabels(page) {
+  const fields = await extractPageFields(page).catch(() => []);
+  return new Set(fields.map(f => f.label).filter(Boolean));
+}
+
+module.exports = {
+  fillFields,
+  uploadFile,
+  findNextButton,
+  findSubmitButton,
+  setFieldValue,
+  typeFieldValue,
+  extractPageFields,
+  semanticFindField,
+  waitForStableDOM,
+  snapshotFieldLabels,
+  selectRadioOption,
+  clickCheckbox,
+};