Visual Exploration

Visual Exploration Methodology

Document behavioral intelligence through browser automation and visual observation. Every screenshot is an empirical observation. Every interaction sequence is a behavioral flow. This mode captures what the user SEES and what the system DOES in response to user actions.

When to Use This Mode

Visual exploration activates when:

• The target is a web application with a UI
• The discovery inventory identifies a running web UI accessible via HTTP
• A running instance of the target is accessible via HTTP

This mode requires a running instance of the target application and browser automation capabilities (Playwright, Puppeteer, or equivalent). All output is RAW (screenshots and flow documentation capture the target's UI in detail).

Targets without a web UI get no useful signal from this mode — skip it.

Why Visual Exploration Matters

Source code tells you what the system CAN do. Tests tell you what the system MUST do. Visual exploration tells you what the system LOOKS LIKE while doing it. This is behavioral intelligence that no other mode captures:

• Affordances -- what actions does the UI present as available?
• Feedback -- how does the system communicate success, failure, and state changes?
• Navigation structure -- how are features organized from the user's perspective?
• State representation -- how does the UI change as the system's state changes?
• Accessibility -- is the interface usable with keyboard, screen reader, or at different sizes?

Phase 1: Initial Reconnaissance

Goal: Navigate to the root URL, capture the landing page, and identify the application type, auth requirements, and available affordances.

1.1 Landing Page Capture

# Navigate to root URL and screenshot
# (Using Playwright as reference; adapt to available browser automation)

const page = await browser.newPage();
await page.goto(ROOT_URL, { waitUntil: 'networkidle' });
await page.screenshot({ path: 'workspace/raw/runtime/visual/screenshots/001-landing.png', fullPage: true });

1.2 Initial Assessment

Document:

• Application type -- SPA, MPA, dashboard, wizard, documentation site, etc.
• Authentication -- does the landing page require login? Is there a signup flow?
• Primary navigation -- top nav, sidebar, hamburger menu, tabs, breadcrumbs?
• Visible affordances -- buttons, links, forms, search bars, dropdowns visible on the landing page
• Branding and layout -- header, footer, sidebar, content area dimensions

1.3 Auth Handling

If authentication is required:

1. Screenshot the login page
2. Document the auth method (username/password, OAuth, SSO, API key)
3. If test credentials are available, authenticate and screenshot the post-login state
4. If no credentials are available, document the gate and explore only the unauthenticated surface

Phase 2: Navigation Mapping

Goal: Click every navigation element, screenshot each page, and document the complete navigation tree.

2.1 Identify Navigation Elements

// Extract all navigation links
const navLinks = await page.$$eval('nav a, [role="navigation"] a, .sidebar a, .menu a, header a', 
  links => links.map(a => ({ text: a.textContent.trim(), href: a.href }))
);

2.2 Systematic Traversal

For each navigation element:

1. Click the element (or navigate to the href)
2. Wait for the page to settle (network idle or DOM stable)
3. Take a full-page screenshot
4. Record the URL, page title, and visible heading
5. Identify sub-navigation elements on the new page

for (const [index, link] of navLinks.entries()) {
  await page.goto(link.href, { waitUntil: 'networkidle' });
  await page.screenshot({ 
    path: `workspace/raw/runtime/visual/screenshots/nav-${String(index).padStart(3, '0')}-${slugify(link.text)}.png`,
    fullPage: true 
  });
}

2.3 Navigation Tree Output

Write to workspace/raw/runtime/visual/navigation-map.md:

## Navigation Tree

- **Home** (`/`) -- screenshot: 001-landing.png
  - **Dashboard** (`/dashboard`) -- screenshot: nav-001-dashboard.png
    - **Analytics** (`/dashboard/analytics`) -- screenshot: nav-002-analytics.png
    - **Reports** (`/dashboard/reports`) -- screenshot: nav-003-reports.png
  - **Settings** (`/settings`) -- screenshot: nav-004-settings.png
    - **Profile** (`/settings/profile`) -- screenshot: nav-005-profile.png
    - **Billing** (`/settings/billing`) -- screenshot: nav-006-billing.png

Phase 3: Interaction Documentation

Goal: For each page, identify interactive elements, interact with them, and capture before/after screenshots documenting the system's feedback.

3.1 Element Inventory

For each page, identify:

• Forms -- text inputs, selects, checkboxes, radio buttons, textareas, file uploads
• Buttons -- submit buttons, action buttons, toggle buttons
• Dropdowns -- select menus, custom dropdown components
• Modals/dialogs -- elements that trigger overlay content
• Expandable sections -- accordions, collapsible panels, "show more" links
• Interactive widgets -- date pickers, sliders, color pickers, drag-and-drop zones

const interactiveElements = await page.$$eval(
  'button, input, select, textarea, [role="button"], [role="tab"], [onclick], a[href="#"]',
  els => els.map(el => ({
    tag: el.tagName,
    type: el.type || '',
    text: el.textContent?.trim().substring(0, 50),
    id: el.id,
    name: el.name,
    ariaLabel: el.getAttribute('aria-label'),
  }))
);

3.2 Interaction Capture

For each interactive element:

1. Before screenshot -- capture the page state before interaction
2. Interact -- click, type, select, toggle
3. After screenshot -- capture the page state after interaction
4. Document feedback -- what changed? Error message? Success toast? New content?

// Example: form submission
await page.screenshot({ path: `screenshots/form-${name}-before.png` });
await page.fill('input[name="email"]', 'test@example.com');
await page.click('button[type="submit"]');
await page.waitForTimeout(1000); // Allow time for feedback
await page.screenshot({ path: `screenshots/form-${name}-after.png` });

3.3 Page Inventory Output

Write to workspace/raw/runtime/visual/page-inventory.md:

## Page: Settings > Profile

**URL:** `/settings/profile`
**Screenshot:** nav-005-profile.png

### Interactive Elements

| Element | Type | Action Taken | Feedback | Screenshots |
|---------|------|-------------|----------|-------------|
| Display Name | text input | Typed "Test User" | No immediate feedback | form-profile-before.png, form-profile-after.png |
| Save | submit button | Clicked | Success toast: "Profile updated" | form-profile-save.png |
| Avatar | file upload | Uploaded test.png | Preview updated | form-profile-avatar.png |

Phase 4: Flow Documentation

Goal: Document end-to-end user flows with screenshots at every state transition.

4.1 Core Flows to Document

Document these flows whenever they exist: