@detiq/crawler 0.1.3

package/src/interactive-probe.ts

@@ -0,0 +1,623 @@
+/**
+ * Interactive Probe — Phase 2 Dynamic Observation
+ *
+ * The static crawl captures DOM structure at rest. This module runs AFTER the static crawl
+ * to observe dynamic behaviour by actually interacting with the UI:
+ *
+ *   1. Empty submit  → captures required-field validation error messages
+ *   2. Invalid format → captures format validation errors (bad email, short password)
+ *   3. Button clicks → captures modal/dialog contents
+ *   4. Select changes → captures conditional reveals (show/hide logic)
+ *   5. Success paths → captures toast/banner messages (where input is safe)
+ *
+ * Results are stored as KnowledgeChunks (sourceType='probe') and update the
+ * ERROR_CATALOGUE + INTERACTION_PATTERNS skill files with real observed data
+ * instead of LLM inference.
+ *
+ * Call signature: probeScreen(page, screenId, elements, opts)
+ * Called from crawlProject() after static element extraction when opts.interactive=true.
+ */
+
+import type { Page } from 'playwright';
+import { AppBrain } from '@detiq/app-brain';
+
+export interface ProbeElementFact {
+  meaning: string;
+  role: string;
+  expectedData?: string;
+}
+
+export interface ValidationError {
+  field: string;
+  trigger: 'empty_submit' | 'invalid_format' | 'boundary';
+  errorText: string;
+}
+
+export interface SuccessMessage {
+  type: 'toast' | 'inline_success' | 'redirect';
+  content: string;
+}
+
+export interface ModalObservation {
+  triggerElement: string;
+  title: string;
+  content: string;
+  fields: string[];
+}
+
+export interface ConditionalReveal {
+  triggerElement: string;
+  triggerValue: string;
+  revealedText: string;
+}
+
+export interface ProbeResult {
+  screenId: string;
+  url: string;
+  validationErrors: ValidationError[];
+  successMessages: SuccessMessage[];
+  modals: ModalObservation[];
+  conditionals: ConditionalReveal[];
+  loadingPatterns: string[];
+}
+
+// ── CSS selectors that reliably find error messages across frameworks ────────
+const ERROR_SELECTORS = [
+  '[role="alert"]',
+  '[aria-live="assertive"]',
+  '[aria-live="polite"]',
+  '.invalid-feedback',
+  '.field-error',
+  '.error-message',
+  '.form-error',
+  '.validation-error',
+  '[class*="error" i]',
+  '[class*="invalid" i]',
+  '[class*="Error"]',
+  'p.text-red-500', 'p.text-red-600', 'p.text-destructive', 'p.text-danger',
+  '[data-error]', '[data-invalid]',
+  '.ant-form-item-explain-error', // Ant Design
+  '.el-form-item__error',          // Element UI
+  '.chakra-form__error-message',   // Chakra UI
+  '.mantine-InputWrapper-error',   // Mantine
+].join(', ');
+
+// ── Toast / notification selectors ───────────────────────────────────────────
+const TOAST_SELECTORS = [
+  '[role="status"]',
+  '[data-sonner-toast]',
+  '[data-toast]',
+  '[data-hot-toast]',
+  '.Toastify__toast',
+  '.toast-message',
+  '.notification-body',
+  '.notistack-snackbar',
+  '[class*="toast" i]',
+  '[class*="Toast"]',
+  '[class*="snackbar" i]',
+  '[class*="notification" i]',
+].join(', ');
+
+/** Wait up to `maxMs` for any selector to appear, then return its text content. */
+async function waitForAny(page: Page, selector: string, maxMs = 2500): Promise<string[]> {
+  try {
+    await page.waitForSelector(selector, { timeout: maxMs, state: 'visible' });
+  } catch { return []; }
+  return page.$$eval(selector, (els) =>
+    els.map((el) => (el as HTMLElement).innerText?.replace(/\s+/g, ' ').trim()).filter(Boolean)
+  );
+}
+
+/** Collect all currently-visible error messages. */
+async function collectErrors(page: Page): Promise<string[]> {
+  try {
+    return page.$$eval(ERROR_SELECTORS, (els) =>
+      els
+        .filter((el) => {
+          const style = window.getComputedStyle(el);
+          return style.display !== 'none' && style.visibility !== 'hidden' && (el as HTMLElement).innerText?.trim().length > 0;
+        })
+        .map((el) => (el as HTMLElement).innerText?.replace(/\s+/g, ' ').trim())
+        .filter(Boolean)
+    );
+  } catch { return []; }
+}
+
+/** Collect any visible toast / notification content. */
+async function collectToasts(page: Page): Promise<string[]> {
+  try {
+    return page.$$eval(TOAST_SELECTORS, (els) =>
+      els
+        .filter((el) => {
+          const style = window.getComputedStyle(el);
+          return style.display !== 'none' && (el as HTMLElement).innerText?.trim().length > 0;
+        })
+        .map((el) => (el as HTMLElement).innerText?.replace(/\s+/g, ' ').trim())
+        .filter(Boolean)
+    );
+  } catch { return []; }
+}
+
+/** Find the primary submit button on the page. */
+async function findSubmitButton(page: Page): Promise<string | null> {
+  return page.evaluate(() => {
+    const SUBMIT_KW = /submit|send|save|create|confirm|continue|proceed|register|sign.?in|log.?in|apply|verify|search|next|finish|complete|order|buy|checkout/i;
+    const candidates = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"]')) as HTMLElement[];
+    const primary = candidates.find((el) => {
+      const style = window.getComputedStyle(el);
+      if (style.display === 'none' || style.visibility === 'hidden') return false;
+      const text = el.innerText || (el as HTMLInputElement).value || el.getAttribute('aria-label') || '';
+      return SUBMIT_KW.test(text);
+    });
+    if (!primary) return null;
+    return primary.getAttribute('data-testid') || primary.getAttribute('aria-label') || primary.innerText?.trim().slice(0, 60);
+  });
+}
+
+/** Find all modal-trigger buttons (non-submit buttons). */
+async function findModalTriggers(page: Page): Promise<Array<{ selector: string; label: string }>> {
+  return page.evaluate(() => {
+    const SKIP = /submit|send|save|create|log.?in|sign.?in|register|continue|checkout|buy|order|search|close|cancel|dismiss/i;
+    const NAV_PARENTS = new Set(['NAV', 'HEADER', 'FOOTER']);
+    return Array.from(document.querySelectorAll('button, [role="button"]'))
+      .filter((el) => {
+        const style = window.getComputedStyle(el as HTMLElement);
+        if (style.display === 'none' || style.visibility === 'hidden') return false;
+        const label = (el as HTMLElement).innerText?.trim() || el.getAttribute('aria-label') || '';
+        if (!label || SKIP.test(label)) return false;
+        // Skip nav chrome
+        let p = el.parentElement;
+        while (p) { if (NAV_PARENTS.has(p.tagName)) return false; p = p.parentElement; }
+        return true;
+      })
+      .slice(0, 8) // probe at most 8 buttons per screen to keep it fast
+      .map((el) => {
+        const label = (el as HTMLElement).innerText?.trim() || el.getAttribute('aria-label') || 'button';
+        return { selector: `[aria-label="${label}"]`, label: label.slice(0, 60) };
+      });
+  });
+}
+
+/** Try to interact with select elements and observe conditional reveals. */
+async function probeConditionals(page: Page): Promise<ConditionalReveal[]> {
+  const results: ConditionalReveal[] = [];
+  try {
+    const selects = await page.$$('select');
+    for (const sel of selects.slice(0, 5)) {
+      const label = await sel.getAttribute('aria-label') || await sel.getAttribute('name') || 'select';
+      const options = await sel.$$eval('option', (opts) => opts.slice(1, 3).map((o) => ({ value: o.value, text: o.textContent?.trim() })));
+      for (const opt of options) {
+        if (!opt.value) continue;
+        const domBefore = await page.evaluate(() => document.body.innerText.length);
+        await sel.selectOption(opt.value);
+        await page.waitForTimeout(500);
+        const domAfter = await page.evaluate(() => document.body.innerText.length);
+        if (Math.abs(domAfter - domBefore) > 50) {
+          const revealed = await page.evaluate(() => {
+            // Grab text from any newly-visible sections
+            return Array.from(document.querySelectorAll('[data-conditional],[data-show],[class*="conditional"]'))
+              .filter((el) => window.getComputedStyle(el).display !== 'none')
+              .map((el) => (el as HTMLElement).innerText?.trim())
+              .filter((t) => t && t.length > 10)
+              .slice(0, 3)
+              .join(' | ');
+          });
+          if (revealed) {
+            results.push({ triggerElement: label, triggerValue: opt.text || opt.value, revealedText: revealed.slice(0, 200) });
+          }
+        }
+      }
+    }
+  } catch { /* non-fatal */ }
+  return results;
+}
+
+/**
+ * Run interactive probing on a single screen page.
+ * The page must already be navigated to the screen URL.
+ * `elements` is the output of the static extractElements pass.
+ */
+export async function probeScreen(
+  page: Page,
+  screenId: string,
+  url: string,
+  elements: ProbeElementFact[],
+): Promise<ProbeResult> {
+  const result: ProbeResult = {
+    screenId, url,
+    validationErrors: [], successMessages: [], modals: [], conditionals: [], loadingPatterns: [],
+  };
+
+  const formInputs = elements.filter((e) =>
+    /input|text|email|password|tel|search|textarea|select/i.test(e.role)
+  );
+  const hasForm = formInputs.length > 0;
+
+  // ── Probe 1: Empty submit → capture required-field errors ────────────────────
+  if (hasForm) {
+    try {
+      const submitLabel = await findSubmitButton(page);
+      if (submitLabel) {
+        // Click submit with no data filled in
+        const submitBtn = page.locator(`button:has-text("${submitLabel}")`).first();
+        await submitBtn.click({ timeout: 2000 });
+        await page.waitForTimeout(1500);
+
+        const errors = await collectErrors(page);
+        for (const errorText of errors) {
+          // Try to match error back to a field
+          const matchedField = formInputs.find((el) =>
+            errorText.toLowerCase().includes(el.meaning.toLowerCase().split(' ')[0]) ||
+            el.meaning.toLowerCase().includes(errorText.toLowerCase().split(' ')[0])
+          );
+          result.validationErrors.push({
+            field: matchedField?.meaning ?? 'unknown',
+            trigger: 'empty_submit',
+            errorText: errorText.slice(0, 150),
+          });
+        }
+
+        // Check for loading state text during submit
+        const loadingText = await page.evaluate(() => {
+          const loading = Array.from(document.querySelectorAll('button, [aria-busy="true"], [class*="loading" i], [class*="spinner" i]'))
+            .map((el) => (el as HTMLElement).innerText?.trim())
+            .filter((t) => t && /loading|saving|submitting|sending|processing/i.test(t));
+          return loading.slice(0, 3);
+        });
+        result.loadingPatterns.push(...loadingText);
+      }
+    } catch { /* non-fatal — form probe failed, continue */ }
+  }
+
+  // ── Probe 2: Invalid format inputs ──────────────────────────────────────────
+  if (hasForm) {
+    try {
+      const emailField = formInputs.find((e) => e.expectedData === 'valid_email' || /email/i.test(e.meaning));
+      const passwordField = formInputs.find((e) => e.expectedData === 'password' || /password/i.test(e.meaning));
+
+      if (emailField) {
+        const emailLocator = page.locator('input[type="email"], input[name*="email"], input[placeholder*="email" i]').first();
+        try {
+          await emailLocator.fill('notanemail', { timeout: 1000 });
+          await emailLocator.blur();
+          await page.waitForTimeout(600);
+          const errors = await collectErrors(page);
+          for (const errorText of errors) {
+            result.validationErrors.push({ field: emailField.meaning, trigger: 'invalid_format', errorText: errorText.slice(0, 150) });
+          }
+        } catch { /* locator not found */ }
+      }
+
+      if (passwordField) {
+        const pwLocator = page.locator('input[type="password"]').first();
+        try {
+          await pwLocator.fill('123', { timeout: 1000 });
+          await pwLocator.blur();
+          await page.waitForTimeout(600);
+          const errors = await collectErrors(page);
+          for (const errorText of errors) {
+            if (!result.validationErrors.some((e) => e.errorText === errorText)) {
+              result.validationErrors.push({ field: passwordField.meaning, trigger: 'invalid_format', errorText: errorText.slice(0, 150) });
+            }
+          }
+        } catch { /* locator not found */ }
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  // ── Probe 3: Button clicks → discover modal/dialog contents ─────────────────
+  try {
+    const triggers = await findModalTriggers(page);
+    for (const trigger of triggers) {
+      try {
+        const btn = page.locator(`button:has-text("${trigger.label}")`).first();
+        const domBefore = await page.evaluate(() => document.body.innerText.length);
+
+        await btn.click({ timeout: 1500 });
+        await page.waitForTimeout(1000);
+
+        // Check if a dialog/modal appeared
+        const dialogText = await page.evaluate(() => {
+          const DIALOG_SEL = '[role="dialog"], [role="alertdialog"], .modal, .Modal, [class*="modal" i], [class*="dialog" i], [class*="Dialog"]';
+          const dialogs = Array.from(document.querySelectorAll(DIALOG_SEL))
+            .filter((el) => window.getComputedStyle(el).display !== 'none');
+          if (dialogs.length === 0) return null;
+          const d = dialogs[0] as HTMLElement;
+          const title = d.querySelector('[role="heading"], h1, h2, h3')?.textContent?.trim() || '';
+          const content = d.innerText?.replace(/\s+/g, ' ').trim().slice(0, 400);
+          const fields = Array.from(d.querySelectorAll('input, select, textarea, button'))
+            .map((f) => (f as HTMLElement).getAttribute('aria-label') || (f as HTMLElement).getAttribute('placeholder') || (f as HTMLInputElement).value || '')
+            .filter((t) => t.trim().length > 0);
+          return { title, content, fields };
+        });
+
+        if (dialogText && dialogText.content.length > 20) {
+          result.modals.push({
+            triggerElement: trigger.label,
+            title: dialogText.title,
+            content: dialogText.content,
+            fields: dialogText.fields.slice(0, 10),
+          });
+        }
+
+        // Dismiss: Escape key first, then close button
+        await page.keyboard.press('Escape');
+        await page.waitForTimeout(400);
+
+        // Check if toast appeared after the click
+        const toasts = await collectToasts(page);
+        for (const t of toasts) {
+          if (t.length > 5) result.successMessages.push({ type: 'toast', content: t.slice(0, 200) });
+        }
+      } catch { /* this button's probe failed, try next */ }
+    }
+  } catch { /* non-fatal */ }
+
+  // ── Probe 4: Select/radio → conditional reveals ──────────────────────────────
+  try {
+    const conditionals = await probeConditionals(page);
+    result.conditionals.push(...conditionals);
+  } catch { /* non-fatal */ }
+
+  return result;
+}
+
+/** Phase 5: Convert ProbeResult to typed ProbeObservationFact rows for direct DB storage. */
+export function probeResultToObservations(result: ProbeResult): Array<{
+  elementMeaning: string; observationType: string; observedText: string; triggeredBy: string;
+}> {
+  const obs: Array<{ elementMeaning: string; observationType: string; observedText: string; triggeredBy: string }> = [];
+  for (const ve of result.validationErrors) {
+    obs.push({ elementMeaning: ve.field, observationType: 'VALIDATION_ERROR', observedText: ve.errorText, triggeredBy: ve.trigger });
+  }
+  for (const sm of result.successMessages) {
+    obs.push({ elementMeaning: '(page)', observationType: 'SUCCESS_TOAST', observedText: sm.content, triggeredBy: sm.type });
+  }
+  for (const m of result.modals) {
+    obs.push({ elementMeaning: m.triggerElement, observationType: 'MODAL', observedText: [m.title, m.content].filter(Boolean).join(' — ').slice(0, 500), triggeredBy: `button_click:${m.triggerElement}` });
+  }
+  for (const c of result.conditionals) {
+    obs.push({ elementMeaning: c.triggerElement, observationType: 'CONDITIONAL_REVEAL', observedText: c.revealedText, triggeredBy: `select_change:${c.triggerElement}:${c.triggerValue}` });
+  }
+  for (const lp of result.loadingPatterns) {
+    obs.push({ elementMeaning: '(submit button)', observationType: 'LOADING_STATE', observedText: lp, triggeredBy: 'form_submit' });
+  }
+  return obs;
+}
+
+/**
+ * Convert a ProbeResult into markdown to store as KnowledgeChunks
+ * and update ERROR_CATALOGUE + INTERACTION_PATTERNS skill files.
+ */
+export function probeResultToMarkdown(result: ProbeResult): {
+  errorCatalogueChunk: string;
+  interactionPatternsChunk: string;
+} {
+  const lines: string[] = [`## Probe Observations — ${result.url}\n`];
+
+  if (result.validationErrors.length > 0) {
+    lines.push('### Validation Errors (observed)');
+    for (const ve of result.validationErrors) {
+      lines.push(`- **${ve.field}** (${ve.trigger}): "${ve.errorText}"`);
+    }
+  }
+
+  if (result.successMessages.length > 0) {
+    lines.push('\n### Success / Feedback Messages (observed)');
+    for (const sm of result.successMessages) {
+      lines.push(`- ${sm.type}: "${sm.content}"`);
+    }
+  }
+
+  if (result.modals.length > 0) {
+    lines.push('\n### Modal / Dialog Contents (observed)');
+    for (const m of result.modals) {
+      lines.push(`- **Trigger:** ${m.triggerElement}`);
+      if (m.title) lines.push(`  - Title: ${m.title}`);
+      lines.push(`  - Content: ${m.content.slice(0, 200)}`);
+      if (m.fields.length > 0) lines.push(`  - Fields: ${m.fields.join(', ')}`);
+    }
+  }
+
+  if (result.conditionals.length > 0) {
+    lines.push('\n### Conditional UI (observed)');
+    for (const c of result.conditionals) {
+      lines.push(`- **${c.triggerElement}** = "${c.triggerValue}" reveals: ${c.revealedText}`);
+    }
+  }
+
+  if (result.loadingPatterns.length > 0) {
+    lines.push('\n### Loading State Text (observed)');
+    for (const lp of result.loadingPatterns) lines.push(`- "${lp}"`);
+  }
+
+  const full = lines.join('\n');
+
+  const errorSection = result.validationErrors.length > 0
+    ? `## Real Validation Errors — ${result.url}\n` +
+      result.validationErrors.map((e) => `- **${e.field}**: "${e.errorText}"`).join('\n')
+    : '';
+
+  const interactionSection = [
+    result.successMessages.length > 0
+      ? `## Success Messages — ${result.url}\n` + result.successMessages.map((s) => `- ${s.type}: "${s.content}"`).join('\n')
+      : '',
+    result.loadingPatterns.length > 0
+      ? `## Loading Patterns — ${result.url}\n` + result.loadingPatterns.map((lp) => `- "${lp}"`).join('\n')
+      : '',
+    result.modals.length > 0
+      ? `## Modal Contents — ${result.url}\n` + result.modals.map((m) => `### ${m.triggerElement}\n${m.content}`).join('\n')
+      : '',
+  ].filter(Boolean).join('\n\n');
+
+  return {
+    errorCatalogueChunk: errorSection,
+    interactionPatternsChunk: interactionSection,
+  };
+}
+
+/**
+ * Run interactive probing for all screens discovered in a crawl session.
+ * Called from crawlProject() when opts.interactive = true.
+ */
+export async function probeAllScreens(
+  page: any,
+  tenantId: string,
+  projectId: string,
+  discovered: Array<{ url: string; screenId?: string; elements?: any[] }>,
+  onProgress?: (pct: number, step: string) => Promise<void>,
+): Promise<void> {
+  const probeable = discovered.filter((d) => d.screenId && d.url && !d.url.includes('#'));
+  if (probeable.length === 0) return;
+
+  const errorCatalogueChunks: string[] = [];
+  const interactionChunks: string[] = [];
+
+  for (let i = 0; i < probeable.length; i++) {
+    const screen = probeable[i];
+    const pct = 88 + Math.round((i / probeable.length) * 10);
+    await onProgress?.(pct, `Probing screen ${i + 1}/${probeable.length}: ${screen.url}`);
+
+    try {
+      // Navigate to screen
+      if (page.url() !== screen.url) {
+        await page.goto(screen.url, { waitUntil: 'domcontentloaded' });
+        await page.waitForTimeout(1500); // SPA hydration
+      }
+
+      const result = await probeScreen(page, screen.screenId!, screen.url, screen.elements ?? []);
+
+      // Phase 5: save structured probe observations (replaces per-re-probe)
+      const observations = probeResultToObservations(result);
+      if (observations.length > 0) {
+        await AppBrain.saveProbeObservations(tenantId, projectId, screen.screenId!, observations).catch(console.warn);
+      }
+
+      // Store raw probe result as KnowledgeChunk (kept for BM25 / oversized projects)
+      const md = probeResultToMarkdown(result);
+      if (md.errorCatalogueChunk) errorCatalogueChunks.push(md.errorCatalogueChunk);
+      if (md.interactionPatternsChunk) interactionChunks.push(md.interactionPatternsChunk);
+
+      const probeMarkdown = [md.errorCatalogueChunk, md.interactionPatternsChunk].filter(Boolean).join('\n\n');
+      if (probeMarkdown.length > 50) {
+        await AppBrain.saveKnowledgeChunk(tenantId, projectId, 'probe', screen.screenId!, probeMarkdown, `Probe — ${screen.url}`).catch(console.warn);
+      }
+
+      if (result.validationErrors.length > 0) {
+        console.log(`[probe] ${screen.url}: ${result.validationErrors.length} validation errors, ${result.modals.length} modals`);
+      }
+    } catch (err) {
+      console.warn(`[probe] ✗ ${screen.url}:`, err instanceof Error ? err.message : err);
+    }
+  }
+
+  // Update ERROR_CATALOGUE skill file with all real observed errors
+  if (errorCatalogueChunks.length > 0) {
+    const combined = `# Error Catalogue (Real Observed — Interactive Probe)\n\n${errorCatalogueChunks.join('\n\n')}`;
+    await AppBrain.upsertSkillFile(tenantId, projectId, 'ERROR_CATALOGUE', combined, {
+      summary: `Real validation error messages observed via interactive probe across ${errorCatalogueChunks.length} screens`,
+      scope: 'PROJECT',
+    }).catch(console.warn);
+  }
+
+  // Update INTERACTION_PATTERNS skill file with real observed patterns
+  if (interactionChunks.length > 0) {
+    const combined = `# Interaction Patterns (Real Observed — Interactive Probe)\n\n${interactionChunks.join('\n\n')}`;
+    await AppBrain.upsertSkillFile(tenantId, projectId, 'INTERACTION_PATTERNS', combined, {
+      summary: `Real loading states, success messages, and modal contents observed via interactive probe`,
+      scope: 'PROJECT',
+    }).catch(console.warn);
+  }
+
+  await onProgress?.(98, 'Interactive probe complete');
+  console.log(`[probe] Probed ${probeable.length} screens. Errors: ${errorCatalogueChunks.length}, Interactions: ${interactionChunks.length}`);
+}
+
+// ── Keyboard Navigation Probe ────────────────────────────────────────────────
+
+export interface FocusableElement {
+  tag: string;
+  role: string | null;
+  ariaLabel: string | null;
+  text: string | null;
+  hasFocusIndicator: boolean;
+  tabIndex: number | null;
+}
+
+export interface KeyboardNavResult {
+  focusableCount: number;
+  elementsWithNoFocusIndicator: number;
+  sequence: FocusableElement[];
+  issues: string[];
+}
+
+/**
+ * Probe keyboard navigation accessibility by pressing Tab up to 50 times and
+ * recording each focused element's properties and focus-indicator visibility.
+ * Stops early if focus wraps back to the start or hits the same element twice.
+ */
+export async function probeKeyboardNav(page: Page): Promise<KeyboardNavResult> {
+  const sequence: FocusableElement[] = [];
+  const issues: string[] = [];
+  const seenKeys = new Set<string>();
+  let firstKey: string | null = null;
+
+  for (let i = 0; i < 50; i++) {
+    await page.keyboard.press('Tab');
+
+    const el = await page.evaluate(() => {
+      const active = document.activeElement as HTMLElement | null;
+      if (!active || active === document.body) return null;
+      const outline = window.getComputedStyle(active).outline;
+      return {
+        tag: active.tagName.toLowerCase(),
+        role: active.getAttribute('role'),
+        ariaLabel: active.getAttribute('aria-label'),
+        text: (active.innerText ?? '').trim().slice(0, 60) || null,
+        outline,
+        tabIndex: active.tabIndex ?? null,
+      };
+    });
+
+    if (!el) break;
+
+    const hasFocusIndicator =
+      el.outline !== 'none' &&
+      el.outline !== '' &&
+      !el.outline.startsWith('0px') &&
+      !el.outline.startsWith('rgba(0, 0, 0, 0)') &&
+      !el.outline.startsWith('rgba(0,0,0,0)');
+
+    const focusable: FocusableElement = {
+      tag: el.tag,
+      role: el.role,
+      ariaLabel: el.ariaLabel,
+      text: el.text,
+      hasFocusIndicator,
+      tabIndex: el.tabIndex,
+    };
+
+    const key = `${el.tag}|${el.text ?? ''}|${el.role ?? ''}`;
+
+    if (i === 0) {
+      firstKey = key;
+    } else if (key === firstKey || seenKeys.has(key)) {
+      // Focus wrapped back to start or hit a duplicate — stop probing
+      break;
+    }
+
+    seenKeys.add(key);
+    sequence.push(focusable);
+
+    if (!hasFocusIndicator) {
+      issues.push(`Element #${i + 1} (${el.tag}) has no visible focus indicator`);
+    }
+  }
+
+  return {
+    focusableCount: sequence.length,
+    elementsWithNoFocusIndicator: issues.length,
+    sequence,
+    issues,
+  };
+}