halo-agent 1.1.0

package/scanPage.js

@@ -0,0 +1,606 @@
+'use strict';
+
+/**
+ * scanPage.js — Per-ATS page scanner.
+ *
+ * Returns a normalized field map for every visible fillable field on the page:
+ *   [ { selector, label, type, tag, inputType, value, category } ]
+ *
+ * category is one of:
+ *   'profile'   — standard identity field (name, email, phone, resume, etc.)
+ *   'custom'    — company-specific question (answered via HALO memory or AI)
+ *   'eeo'       — Equal Employment Opportunity / demographic
+ *   'consent'   — checkbox consent, marketing opt-in
+ *   'ignore'    — captcha, hidden, already filled, utility inputs
+ *
+ * Each ATS has its own scanner because they embed fields differently:
+ *   greenhouse  — id= attrs are stable across ALL companies
+ *   lever       — name= attrs stable, full name in single field
+ *   ashby       — _systemfield_* system names, UUID names for custom fields
+ *   workday     — data-automation-id for nav/buttons, form fields in iframe (vision)
+ *   icims       — everything inside a named iframe
+ *   generic     — label-text walk for any other ATS
+ *
+ * IMPORTANT: this scanner runs on the live page via Playwright, not on saved HTML.
+ * It always returns what is actually visible right now.
+ */
+
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Run in-browser DOM scan. Returns raw field list before enrichment.
+ * This is the same getFieldLabel logic from extractPageFields but extended
+ * to also capture data-automation-id and to distinguish radio/checkbox groups.
+ */
+async function domScan(page) {
+  return page.evaluate(() => {
+    function getLabel(el) {
+      // 1. Native label[for]
+      if (el.id) {
+        const lbl = document.querySelector('label[for="' + el.id + '"]');
+        if (lbl) return lbl.textContent.replace(/\s+/g, ' ').trim();
+      }
+      if (el.labels && el.labels[0]) return el.labels[0].textContent.replace(/\s+/g, ' ').trim();
+      // 2. aria-label / aria-labelledby
+      const ariaLabel = el.getAttribute('aria-label');
+      if (ariaLabel) return ariaLabel.trim();
+      const ariaLabelledBy = el.getAttribute('aria-labelledby');
+      if (ariaLabelledBy) {
+        const ids = ariaLabelledBy.split(/\s+/);
+        const text = ids.map(id => { const e = document.getElementById(id); return e ? e.textContent.trim() : ''; }).join(' ').trim();
+        if (text) return text;
+      }
+      // 3. data-label / data-title
+      if (el.dataset.label) return el.dataset.label.trim();
+      if (el.dataset.title) return el.dataset.title.trim();
+      // 4. Preceding siblings — prefer headings, then short generic containers.
+      // Ashby/Lever put <h3>Question text</h3> before the <textarea>, not a <label>.
+      let prev = el.previousElementSibling;
+      while (prev) {
+        const ptag = prev.tagName;
+        if (/^(LABEL|LEGEND)$/.test(ptag)) {
+          const t = prev.textContent.replace(/\s+/g, ' ').trim();
+          if (t) return t;
+        }
+        if (/^H[1-6]$/.test(ptag)) {
+          const t = prev.textContent.replace(/\s+/g, ' ').trim();
+          if (t && t.length < 200) return t;
+        }
+        if (/^(SPAN|DIV|P|STRONG|B)$/.test(ptag)) {
+          const t = prev.textContent.replace(/\s+/g, ' ').trim();
+          if (t && t.length > 0 && t.length < 100) return t;
+        }
+        prev = prev.previousElementSibling;
+      }
+      // 5. Walk up DOM ancestors — look for heading or label inside each level.
+      // Key: Ashby uses <div><h3>Question</h3><p>Description</p><textarea/></div>
+      let parent = el.parentElement;
+      let depth = 0;
+      while (parent && depth < 12) {
+        const labelEl = parent.querySelector('label, legend');
+        if (labelEl && !labelEl.contains(el)) {
+          const t = labelEl.textContent.replace(/\s+/g, ' ').trim();
+          if (t && t.length < 200) return t;
+        }
+        const headingEl = parent.querySelector('h1, h2, h3, h4, h5, h6, strong, b');
+        if (headingEl && !headingEl.contains(el)) {
+          const t = headingEl.textContent.replace(/\s+/g, ' ').trim();
+          if (t && t.length > 3 && t.length < 300) return t;
+        }
+        const classEl = parent.querySelector('[class*="label"], [class*="title"], [class*="question"], [class*="heading"], [class*="prompt"]');
+        if (classEl && !classEl.contains(el)) {
+          const t = classEl.textContent.replace(/\s+/g, ' ').trim();
+          if (t && t.length > 0 && t.length < 200) return t;
+        }
+        parent = parent.parentElement;
+        depth++;
+      }
+      // 6. Fallback: placeholder > name > id
+      return el.placeholder || el.name || el.id || '';
+    }
+
+    const results = [];
+    const seen = new Set();
+
+    document.querySelectorAll('input, textarea, select, [role="combobox"], [contenteditable="true"]').forEach(el => {
+      const type = (el.type || '').toLowerCase();
+      // Skip utility types
+      if (['hidden', 'submit', 'button', 'image', 'reset'].includes(type)) return;
+      // Skip invisible (but allow radio/checkbox which may be styled-hidden)
+      if (type !== 'radio' && type !== 'checkbox' && type !== 'file') {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return;
+        if (el.offsetParent === null && !el.closest('[role="dialog"]')) return;
+      }
+
+      const label = getLabel(el).replace(/^\*+|\*+$/g, '').trim();
+      const id = el.id || '';
+      const name = el.name || '';
+      const automationId = el.getAttribute('data-automation-id') || '';
+      const testId = el.getAttribute('data-testid') || '';
+      const role = el.getAttribute('role') || '';
+      const tag = el.tagName.toLowerCase();
+      const currentValue = el.value || '';
+
+      // Build a dedup key
+      const dedupKey = id || name || (label + ':' + type) || el.outerHTML.slice(0, 60);
+      if (seen.has(dedupKey)) return;
+      seen.add(dedupKey);
+
+      // Build the most stable selector
+      let selector = '';
+      if (id) selector = `#${id.replace(/([!"#$%&'()*+,.\/:;<=>?@\[\\\]^`{|}~])/g, '\\$1')}`;
+      else if (name) selector = `[name="${name}"]`;
+      else if (automationId) selector = `[data-automation-id="${automationId}"]`;
+      else if (testId) selector = `[data-testid="${testId}"]`;
+      else if (label) {
+        const escaped = label.replace(/['"\\]/g, '');
+        selector = `${tag}[aria-label="${escaped}"]`;
+      }
+
+      results.push({
+        tag,
+        inputType: type,
+        role,
+        id,
+        name,
+        automationId,
+        testId,
+        label,
+        selector,
+        currentValue,
+        isContentEditable: el.isContentEditable || false,
+      });
+    });
+
+    return results;
+  });
+}
+
+// ─── Profile field classifier ─────────────────────────────────────────────────
+
+// Map from normalized label keywords to profile field name.
+// Order matters — more specific patterns first.
+const PROFILE_PATTERNS = [
+  // Lever-style: single full name field
+  { field: 'full_name',     regex: /^(full\s*name|your\s*name|name)$/i },
+  // Standard first/last
+  { field: 'first_name',    regex: /first[\s_-]?name|given[\s_-]?name|forename/i },
+  { field: 'last_name',     regex: /last[\s_-]?name|family[\s_-]?name|surname/i },
+  { field: 'preferred_name',regex: /preferred[\s_-]?(first\s*)?name|goes\s*by/i },
+  { field: 'email',         regex: /e[\s-]?mail/i },
+  { field: 'phone',         regex: /phone|mobile|telephone|cell/i },
+  { field: 'linkedin',      regex: /linkedin/i },
+  { field: 'github',        regex: /github/i },
+  { field: 'twitter',       regex: /twitter|x\.com/i },
+  { field: 'portfolio',     regex: /portfolio|personal\s*(site|url|website)|website/i },
+  { field: 'location',      regex: /^(location|city|current\s*location)$/i },
+  { field: 'address',       regex: /address\s*(line\s*1)?|street/i },
+  { field: 'city',          regex: /^city$/i },
+  { field: 'state',         regex: /^(state|province|region)$/i },
+  { field: 'zip',           regex: /zip|postal\s*code/i },
+  { field: 'country',       regex: /^country$/i },
+  { field: 'salary',        regex: /salary|compensation|expected\s*pay/i },
+  { field: 'start_date',    regex: /start\s*date|available|earliest.*start/i },
+  { field: 'school',        regex: /school|university|college|institution/i },
+  { field: 'degree',        regex: /degree|qualification/i },
+  { field: 'gpa',           regex: /gpa|grade\s*point/i },
+  { field: 'org',           regex: /^(company|employer|organization|current\s*(company|employer))$/i },
+];
+
+// EEO / demographic patterns
+const EEO_PATTERNS = [
+  /gender|sex$/i,
+  /race|ethnicity|hispanic/i,
+  /veteran/i,
+  /disability|disabled/i,
+  /pronoun/i,
+  /equal\s*opportunity/i,
+  /voluntary\s*self/i,
+  /demographic/i,
+];
+
+// Consent / noise patterns
+const CONSENT_PATTERNS = [
+  /consent|agree|accept|opt.?in|marketing|newsletter/i,
+  /terms\s*(and|&)\s*(conditions|service)/i,
+  /privacy\s*policy/i,
+];
+
+function classifyField(field) {
+  const label = field.label.toLowerCase().trim();
+
+  // Consent checkboxes
+  if (field.inputType === 'checkbox' && CONSENT_PATTERNS.some(r => r.test(label))) {
+    return 'consent';
+  }
+  // EEO
+  if (EEO_PATTERNS.some(r => r.test(label))) return 'eeo';
+
+  // Profile
+  for (const { field: name, regex } of PROFILE_PATTERNS) {
+    if (regex.test(label)) return 'profile:' + name;
+  }
+
+  // Ashby system fields by name attribute
+  if (field.name && field.name.startsWith('_systemfield_')) {
+    const sfName = field.name.replace('_systemfield_', '');
+    if (['name', 'email', 'phone', 'resume', 'linkedin', 'website'].includes(sfName)) {
+      return 'profile:' + (sfName === 'name' ? 'full_name' : sfName);
+    }
+  }
+
+  // Custom (company-specific question)
+  return 'custom';
+}
+
+// ─── ATS-specific scanners ────────────────────────────────────────────────────
+
+/**
+ * Greenhouse scanner.
+ * Fields use id= that matches the field semantic name (first_name, last_name, email, phone, resume).
+ * Custom questions: id starts with 'question_', label from adjacent <label>.
+ */
+async function scanGreenhouse(page) {
+  const raw = await domScan(page);
+  return raw.map(f => {
+    // Greenhouse id= IS the semantic name for system fields
+    const ghSystemIds = { first_name: 'first_name', last_name: 'last_name', preferred_name: 'preferred:preferred_name', email: 'email', phone: 'phone', resume: 'resume', cover_letter: 'cover_letter' };
+    if (f.id && ghSystemIds[f.id]) {
+      return { ...f, category: f.id === 'resume' || f.id === 'cover_letter' ? 'file:' + f.id : 'profile:' + ghSystemIds[f.id] };
+    }
+    // Custom question fields: id like question_12345678
+    if (f.id && /^question_\d+$/.test(f.id)) {
+      return { ...f, category: 'custom' };
+    }
+    // EEO/demographic dropdowns at bottom
+    if (f.id && /^(gender|hispanic_ethnicity|veteran_status|disability_status)$/.test(f.id)) {
+      return { ...f, category: 'eeo' };
+    }
+    // Degree/school fields
+    if (f.id && /^(degree|school|major)/.test(f.id)) {
+      return { ...f, category: 'profile:' + f.id.split('--')[0] };
+    }
+    return { ...f, category: classifyField(f) };
+  }).filter(f => f.category !== 'ignore' && f.inputType !== 'hidden');
+}
+
+/**
+ * Lever scanner.
+ * name= attributes are stable across ALL companies.
+ * Key difference: full name is a SINGLE field (name="name"), NOT first+last.
+ * Custom questions: name starts with "cards[" pattern.
+ */
+async function scanLever(page) {
+  const raw = await domScan(page);
+  return raw.map(f => {
+    const leverSystemNames = {
+      name: 'profile:full_name',
+      email: 'profile:email',
+      phone: 'profile:phone',
+      location: 'profile:location',
+      org: 'profile:org',
+      'urls[LinkedIn]': 'profile:linkedin',
+      'urls[GitHub]': 'profile:github',
+      'urls[Twitter]': 'profile:twitter',
+      'urls[Portfolio]': 'profile:portfolio',
+      'urls[Other]': 'profile:website',
+      comments: 'cover_letter',
+    };
+    if (f.name && leverSystemNames[f.name]) {
+      return { ...f, category: leverSystemNames[f.name] };
+    }
+    if (f.name === 'resume' || f.inputType === 'file') {
+      return { ...f, category: 'file:resume' };
+    }
+    // EEO selects
+    if (f.name && f.name.startsWith('eeo[')) {
+      return { ...f, category: 'eeo' };
+    }
+    // Consent checkboxes
+    if (f.name && f.name.startsWith('consent[')) {
+      return { ...f, category: 'consent' };
+    }
+    // Custom questions: name="cards[{uuid}][field{n}]"
+    if (f.name && f.name.startsWith('cards[')) {
+      return { ...f, category: 'custom' };
+    }
+    return { ...f, category: classifyField(f) };
+  }).filter(f => f.category !== 'ignore');
+}
+
+/**
+ * Ashby scanner.
+ * System fields: name="_systemfield_{name}" — stable across ALL companies.
+ * Custom fields: name="{uuid}" — company-specific, use label text to identify.
+ */
+async function scanAshby(page) {
+  const raw = await domScan(page);
+  return raw.map(f => {
+    if (f.name && f.name.startsWith('_systemfield_')) {
+      const sfField = f.name.replace('_systemfield_', '');
+      const profileMap = { name: 'full_name', email: 'email', phone: 'phone', linkedin: 'linkedin', website: 'portfolio', resume: null };
+      if (sfField === 'resume' || f.inputType === 'file') return { ...f, category: 'file:resume' };
+      if (profileMap[sfField] !== undefined) return { ...f, category: 'profile:' + profileMap[sfField] };
+    }
+    // UUID-named fields are custom questions
+    if (f.name && /^[0-9a-f-]{36}$/.test(f.name)) {
+      return { ...f, category: 'custom' };
+    }
+    if (f.inputType === 'file') return { ...f, category: 'file:resume' };
+    return { ...f, category: classifyField(f) };
+  }).filter(f => f.category !== 'ignore');
+}
+
+/**
+ * Workday scanner.
+ * Form fields live inside a nested iframe (dynamically injected after auth).
+ * We attempt to pierce the iframe and scan its fields.
+ * Falls back to outer DOM scan if iframe isn't accessible.
+ * Navigation buttons use data-automation-id and are NOT included in the field scan
+ * (they're handled by findNextButton/findSubmitButton separately).
+ */
+async function scanWorkday(page) {
+  // Try to find the application iframe
+  let targetPage = page;
+  try {
+    const frames = page.frames();
+    // Workday application form typically loads in a frame whose URL contains 'wd' or is a child of the main frame
+    const appFrame = frames.find(f => {
+      const url = f.url();
+      return url && url !== 'about:blank' && url !== '' && !url.includes('googleapis') && f !== page.mainFrame();
+    });
+    if (appFrame) {
+      // Use the frame as context for domScan
+      const frameFields = await appFrame.evaluate(() => {
+        // Same inline DOM walk — can't call domScan directly in frame context
+        const results = [];
+        document.querySelectorAll('input, textarea, select').forEach(el => {
+          const type = (el.type || '').toLowerCase();
+          if (['hidden', 'submit', 'button', 'image', 'reset'].includes(type)) return;
+          const rect = el.getBoundingClientRect();
+          if (rect.width === 0 && rect.height === 0) return;
+          const automationId = el.getAttribute('data-automation-id') || '';
+          const label = el.getAttribute('aria-label') || el.placeholder || automationId || el.name || el.id || '';
+          results.push({
+            tag: el.tagName.toLowerCase(),
+            inputType: type,
+            id: el.id || '',
+            name: el.name || '',
+            automationId,
+            label,
+            selector: automationId ? `[data-automation-id="${automationId}"]` : (el.id ? `#${el.id}` : `[name="${el.name}"]`),
+            currentValue: el.value || '',
+          });
+        });
+        return results;
+      }).catch(() => []);
+
+      if (frameFields.length > 0) {
+        return frameFields.map(f => ({ ...f, frameUrl: appFrame.url(), category: classifyField(f) }));
+      }
+    }
+  } catch {}
+
+  // Outer DOM fallback (job listing page / sign-in page)
+  const raw = await domScan(page);
+  return raw.map(f => ({ ...f, category: classifyField(f) }));
+}
+
+/**
+ * iCIMS scanner.
+ * All application fields live inside an iframe with a stable title or src pattern.
+ * We pierce the iframe using Playwright frameLocator.
+ */
+async function scanICIMS(page) {
+  // Try named iframe selectors in priority order
+  const iframeSelectors = [
+    'iframe[title*="iCIMS"]',
+    'iframe[src*="icims.com"]',
+    'iframe[id*="icims"]',
+    'iframe[name*="icims"]',
+    'iframe',  // fallback: first iframe
+  ];
+
+  for (const iframeSel of iframeSelectors) {
+    try {
+      const frameCount = await page.locator(iframeSel).count();
+      if (frameCount === 0) continue;
+
+      const frame = page.frameLocator(iframeSel);
+      const innerFields = await frame.locator('input, textarea, select').evaluateAll(elements => {
+        return elements.map(el => {
+          const type = (el.type || '').toLowerCase();
+          if (['hidden', 'submit', 'button', 'image'].includes(type)) return null;
+          let label = '';
+          if (el.id) {
+            const lbl = document.querySelector('label[for="' + el.id + '"]');
+            if (lbl) label = lbl.textContent.trim();
+          }
+          if (!label) label = el.getAttribute('aria-label') || el.placeholder || el.name || el.id || '';
+          return {
+            tag: el.tagName.toLowerCase(),
+            inputType: type,
+            id: el.id || '',
+            name: el.name || '',
+            label: label.trim(),
+            selector: el.id ? `#${el.id}` : (el.name ? `[name="${el.name}"]` : null),
+            currentValue: el.value || '',
+          };
+        }).filter(Boolean);
+      }).catch(() => []);
+
+      if (innerFields.length > 0) {
+        return innerFields.map(f => ({
+          ...f,
+          iframeSelector: iframeSel,
+          category: classifyField(f),
+        }));
+      }
+    } catch {}
+  }
+
+  // Fallback to outer DOM
+  const raw = await domScan(page);
+  return raw.map(f => ({ ...f, category: classifyField(f) }));
+}
+
+/**
+ * Generic scanner for any ATS not explicitly handled.
+ * Uses the full DOM walk with label classification.
+ */
+async function scanGeneric(page) {
+  const raw = await domScan(page);
+  return raw.map(f => ({ ...f, category: classifyField(f) }));
+}
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Scan the current page and return a structured field map.
+ *
+ * @param {import('playwright').Page} page
+ * @param {string} ats  - 'greenhouse' | 'lever' | 'ashby' | 'workday' | 'icims' | 'taleo' | ...
+ * @returns {Promise<ScannedField[]>}
+ *
+ * ScannedField shape:
+ * {
+ *   selector: string,         CSS selector to locate this element
+ *   label: string,            Human-readable label text
+ *   tag: string,              'input' | 'textarea' | 'select'
+ *   inputType: string,        'text' | 'email' | 'radio' | 'checkbox' | 'file' | ...
+ *   name: string,             name= attribute
+ *   id: string,               id= attribute
+ *   automationId: string,     data-automation-id= attribute (Workday)
+ *   currentValue: string,     current field value (empty if unfilled)
+ *   category: string,         'profile:{field}' | 'custom' | 'eeo' | 'consent' | 'file:{field}'
+ *   iframeSelector?: string,  set if field is inside an iframe (iCIMS)
+ * }
+ */
+async function scanPage(page, ats) {
+  const platform = (ats || 'generic').toLowerCase();
+  let fields;
+
+  try {
+    switch (platform) {
+      case 'greenhouse': fields = await scanGreenhouse(page); break;
+      case 'lever':      fields = await scanLever(page);      break;
+      case 'ashby':      fields = await scanAshby(page);      break;
+      case 'workday':    fields = await scanWorkday(page);    break;
+      case 'icims':      fields = await scanICIMS(page);      break;
+      default:           fields = await scanGeneric(page);    break;
+    }
+  } catch (e) {
+    console.warn(`[scanPage] Scanner failed for ${platform}: ${e.message} — falling back to generic`);
+    fields = await scanGeneric(page).catch(() => []);
+  }
+
+  // Filter out already-filled fields and utility noise
+  const out = fields.filter(f => {
+    if (!f.label && !f.selector) return false;
+    if (f.inputType === 'hidden') return false;
+    // Skip recaptcha textarea
+    if (f.name && f.name.includes('g-recaptcha')) return false;
+    return true;
+  });
+
+  console.log(`[scanPage] ${platform}: found ${out.length} fields (${out.filter(f => f.category.startsWith('profile')).length} profile, ${out.filter(f => f.category === 'custom').length} custom, ${out.filter(f => f.category === 'eeo').length} eeo)`);
+  return out;
+}
+
+/**
+ * Given the scanned fields and an AEP profile, return what value to fill for each field.
+ * - Profile fields: look up from profile object
+ * - Custom fields: look up from field_answers (AI pre-generated or on-demand)
+ * - Returns null for fields that have no answer yet (caller fetches AI answer)
+ *
+ * @param {ScannedField[]} fields
+ * @param {object} aep  - Agent Execution Packet (profile_fill, field_answers, cover_letter)
+ * @returns {{ field: ScannedField, value: string|null, source: string }[]}
+ */
+function resolveFieldValues(fields, aep) {
+  const profile = aep.profile_fill || {};
+  const fieldAnswers = aep.field_answers || [];
+
+  // Build label -> answer map from pre-generated AEP answers (case-insensitive)
+  const answerMap = new Map();
+  for (const fa of fieldAnswers) {
+    if (fa.label) answerMap.set(fa.label.toLowerCase().trim(), { value: fa.value, source: fa.source || 'ai' });
+    if (fa.field_id) answerMap.set(fa.field_id.toLowerCase().trim(), { value: fa.value, source: fa.source || 'ai' });
+  }
+
+  // Profile field resolver
+  const profileValues = {
+    full_name: [profile.first_name, profile.last_name].filter(Boolean).join(' '),
+    first_name: profile.first_name || '',
+    last_name: profile.last_name || '',
+    preferred_name: profile.preferred_name || profile.first_name || '',
+    email: profile.email || '',
+    phone: profile.phone || '',
+    linkedin: profile.linkedin || '',
+    github: profile.github || '',
+    twitter: profile.twitter || '',
+    portfolio: profile.portfolio || profile.website || '',
+    website: profile.portfolio || profile.website || '',
+    location: profile.city || profile.location || '',
+    address: profile.address || '',
+    city: profile.city || '',
+    state: profile.state || '',
+    zip: profile.zip || profile.postal || '',
+    country: profile.country || 'United States',
+    org: profile.current_company || profile.org || '',
+    school: profile.school || '',
+    degree: profile.degree || '',
+    gpa: profile.gpa || '',
+    salary: profile.desired_salary || '',
+    start_date: profile.start_date || 'Immediately',
+  };
+
+  return fields.map(field => {
+    const cat = field.category;
+
+    // File upload fields — handled separately by uploadResume()
+    if (cat.startsWith('file:')) {
+      return { field, value: null, source: 'file_upload' };
+    }
+
+    // EEO/consent — skip (handled by vision or user)
+    if (cat === 'eeo' || cat === 'consent') {
+      return { field, value: null, source: 'skip' };
+    }
+
+    // Profile fields
+    if (cat.startsWith('profile:')) {
+      const pfKey = cat.slice('profile:'.length);
+      const val = profileValues[pfKey] || '';
+      // Also check answerMap in case AEP overrides a profile field
+      const override = answerMap.get((field.label || '').toLowerCase().trim());
+      return { field, value: override?.value || val || null, source: val ? 'profile' : 'missing' };
+    }
+
+    // Cover letter special case
+    if (cat === 'cover_letter') {
+      return { field, value: aep.cover_letter || null, source: 'cover_letter' };
+    }
+
+    // Custom question — look up in answer map by label (exact then fuzzy)
+    if (cat === 'custom') {
+      const labelKey = (field.label || '').toLowerCase().trim();
+      // Exact match
+      const exact = answerMap.get(labelKey);
+      if (exact) return { field, value: exact.value, source: exact.source };
+      // Fuzzy: check if any answer label is contained in this label or vice versa
+      for (const [key, ans] of answerMap) {
+        if (key.length > 5 && (labelKey.includes(key) || key.includes(labelKey))) {
+          return { field, value: ans.value, source: ans.source + ':fuzzy' };
+        }
+      }
+      // No answer found — needs AI
+      return { field, value: null, source: 'needs_ai' };
+    }
+
+    return { field, value: null, source: 'unknown' };
+  });
+}
+
+module.exports = { scanPage, resolveFieldValues, classifyField };