@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-visual-strategy/references/journey-schema.md

@@ -0,0 +1,375 @@
+# Journey Schema Reference
+
+This document defines the platform-agnostic journey definition format used for Layer 2 journey-based interaction testing. It is the canonical reference for all skills and agents that create, validate, or execute journey definitions.
+
+## Journey Definition Schema
+
+A journey is a sequence of steps that model a user interaction flow. Each step has a `type` field that determines the required and optional fields.
+
+### Step Types
+
+| Type | Required Fields | Optional Fields | Description |
+|------|----------------|-----------------|-------------|
+| `capture` | `name` | `delay` | Takes a screenshot at a checkpoint. The `name` field becomes the screenshot filename and is used for cross-layer matching. |
+| `invoke` | `target` | `delay` | Clicks or activates a UI element. The `target` field is a selector object (see Element Selector Format). |
+| `setValue` | `target`, `value` | `delay` | Sets a value on an input element. The `target` field is a selector object and `value` is the string to enter. |
+| `settle` | _(none)_ | `timeout`, `condition` | Waits for the UI to stabilize before proceeding. Default timeout is 5000ms. The optional `condition` field describes what "settled" means (e.g., "loading spinner disappears"). |
+
+### Field Definitions
+
+- **`name`** (string) -- Unique identifier for the capture step within its journey. Used as the screenshot filename and for cross-layer screen matching.
+- **`target`** (object) -- Selector object identifying the UI element to interact with. See Element Selector Format below.
+- **`value`** (string) -- The text or value to set on the target element.
+- **`delay`** (number) -- Milliseconds to wait before executing the step. Default: 0.
+- **`timeout`** (number) -- Maximum milliseconds to wait for the settle condition. Default: 5000.
+- **`condition`** (string) -- Human-readable description of what "settled" means. Used by the runner to determine the appropriate wait strategy.
+
+### Example: Login Flow Journey
+
+```json
+{
+  "name": "login-flow",
+  "description": "Navigates to login screen, enters credentials, submits, and captures the resulting dashboard",
+  "preconditions": [
+    "Application is running and showing the main window",
+    "No user is currently logged in"
+  ],
+  "steps": [
+    {
+      "type": "capture",
+      "name": "login-screen"
+    },
+    {
+      "type": "setValue",
+      "target": { "automationId": "usernameInput", "controlType": "textBox" },
+      "value": "testuser@example.com"
+    },
+    {
+      "type": "setValue",
+      "target": { "automationId": "passwordInput", "controlType": "textBox" },
+      "value": "test-password-123"
+    },
+    {
+      "type": "invoke",
+      "target": { "automationId": "loginButton", "controlType": "button" },
+      "delay": 200
+    },
+    {
+      "type": "settle",
+      "timeout": 10000,
+      "condition": "Loading spinner disappears and dashboard content is visible"
+    },
+    {
+      "type": "capture",
+      "name": "dashboard-after-login"
+    }
+  ]
+}
+```
+
+## Element Selector Format
+
+A selector object identifies a UI element in the application's accessibility tree. Selectors are platform-agnostic -- the platform runner translates them into native API calls.
+
+### Selector Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `automationId` | string | The element's automation ID (highest priority). Maps to `AutomationId` on Windows UIA and `identifier` on macOS NSAccessibility. |
+| `controlType` | string | The logical control type (e.g., `button`, `textBox`, `menuItem`). Maps to platform-specific control type enumerations. See the Element Mapping Table below. |
+| `name` | string | The element's accessible name (fallback). Maps to `Name` on Windows UIA and `AXTitle` or `AXDescription` on macOS NSAccessibility. |
+
+### Resolution Order
+
+The platform runner resolves selectors in the following priority order:
+
+1. **Custom mappings lookup** -- If the `target` value is a string (logical name), the runner looks it up in the `customMappings` section of the journey manifest. This returns a platform-specific selector with full native properties.
+2. **Direct `automationId`** -- If the selector has an `automationId` field, the runner searches the accessibility tree for an element with that automation ID. This is the most reliable cross-platform identifier.
+3. **`controlType` + `name` combination** -- If `automationId` is absent or resolution fails, the runner searches for an element matching both the `controlType` (mapped to the platform's native type) and the `name` (accessible name). This is the fallback strategy.
+
+If all resolution strategies fail, the runner reports a `SELECTOR_NOT_FOUND` error for the step.
+
+## Custom Mappings
+
+The `customMappings` section in the journey manifest maps logical component names to platform-specific selectors. This bridges the gap between the journey's platform-agnostic step definitions and the actual accessibility tree of the implementation.
+
+### Structure
+
+```json
+{
+  "customMappings": {
+    "main-navigation": {
+      "windows": {
+        "automationId": "NavHost",
+        "controlType": "Pane",
+        "className": "NavigationView"
+      },
+      "macos": {
+        "role": "AXGroup",
+        "subrole": "AXNavigationBar",
+        "identifier": "MainNavigation"
+      }
+    },
+    "data-table": {
+      "windows": {
+        "automationId": "MainDataGrid",
+        "controlType": "DataGrid",
+        "className": "DataGridView"
+      },
+      "macos": {
+        "role": "AXTable",
+        "subrole": "",
+        "identifier": "MainDataGrid"
+      }
+    }
+  }
+}
+```
+
+### When to Use Custom Mappings
+
+Custom mappings are needed when standard selectors (automationId, controlType, name) are insufficient:
+
+- **Complex or non-standard components** -- Data grids, chart widgets, custom-drawn controls, and composite components that expose non-obvious accessibility trees.
+- **Platform-divergent accessibility trees** -- Components whose accessibility structure differs significantly between Windows UIA and macOS NSAccessibility (e.g., a navigation rail that is a `Pane` on Windows but an `AXGroup` on macOS).
+- **Components with unreliable `automationId`** -- Controls generated by frameworks that assign dynamic or unstable automation IDs.
+- **Deeply nested elements** -- Components where the target element is several levels deep in the accessibility tree and requires class name or subrole disambiguation.
+
+**Note:** `arn-spark-visual-test-engineer` populates custom mappings automatically by scanning the actual implementation's accessibility tree during the spike phase. Manual editing is only needed for fine-tuning.
+
+### Platform-Specific Properties
+
+**Windows (UIA):**
+- `automationId` -- Maps to `AutomationElement.Current.AutomationId`
+- `controlType` -- Maps to `ControlType.ControlTypeId` (e.g., `DataGrid`, `Pane`)
+- `className` -- Maps to `AutomationElement.Current.ClassName` (disambiguation)
+
+**macOS (NSAccessibility):**
+- `role` -- Maps to `AXRole` (e.g., `AXTable`, `AXGroup`, `AXButton`)
+- `subrole` -- Maps to `AXSubrole` (e.g., `AXNavigationBar`, `AXSortButton`)
+- `identifier` -- Maps to `AXIdentifier` (accessibility identifier set by the developer)
+
+## UIA / NSAccessibility Element Mapping Table
+
+This table maps logical control types used in journey step selectors to their platform-native equivalents.
+
+| Logical Type | Windows UIA ControlType | Windows UIA Class | macOS NSAccessibility Role | macOS NSAccessibility Subrole |
+|-------------|------------------------|-------------------|---------------------------|------------------------------|
+| `button` | `Button` | `Button` | `AXButton` | -- |
+| `textBox` | `Edit` | `TextBox`, `TextEdit` | `AXTextField` | -- |
+| `checkBox` | `CheckBox` | `CheckBox` | `AXCheckBox` | -- |
+| `radioButton` | `RadioButton` | `RadioButton` | `AXRadioButton` | -- |
+| `comboBox` | `ComboBox` | `ComboBox` | `AXPopUpButton` | -- |
+| `listItem` | `ListItem` | `ListBoxItem` | `AXCell` | `AXOutlineRow` |
+| `menuItem` | `MenuItem` | `MenuItem` | `AXMenuItem` | -- |
+| `tab` | `TabItem` | `TabItem` | `AXRadioButton` | `AXTabButton` |
+| `treeItem` | `TreeItem` | `TreeViewItem` | `AXRow` | `AXOutlineRow` |
+| `slider` | `Slider` | `Slider` | `AXSlider` | -- |
+| `progressBar` | `ProgressBar` | `ProgressBar` | `AXProgressIndicator` | -- |
+| `dataGrid` | `DataGrid` | `DataGridView` | `AXTable` | -- |
+| `link` | `Hyperlink` | `Hyperlink` | `AXLink` | -- |
+| `image` | `Image` | `Image` | `AXImage` | -- |
+| `window` | `Window` | `Window` | `AXWindow` | `AXStandardWindow` |
+| `scrollBar` | `ScrollBar` | `ScrollBar` | `AXScrollBar` | -- |
+| `toolBar` | `ToolBar` | `ToolBar` | `AXToolbar` | -- |
+| `statusBar` | `StatusBar` | `StatusBar` | `AXGroup` | `AXStatusBar` |
+| `dialog` | `Window` | `Dialog` | `AXSheet` | `AXDialog` |
+| `label` | `Text` | `TextBlock` | `AXStaticText` | -- |
+
+## Platform Runner Contract
+
+Every platform runner must implement the following interface. Runners are platform-specific executables or scripts that consume the platform-agnostic journey manifest and interact with the native accessibility APIs.
+
+### Required Interface
+
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `Load(manifestPath)` | Path to `journey-manifest.json` | Parsed manifest object | Reads and validates the journey manifest. Fails if the schema version is unsupported or the JSON is malformed. |
+| `Resolve(selector, platform)` | Selector object, platform identifier (`windows` or `macos`) | Native element reference | Finds the UI element using the selector resolution order: custom mappings first, then `automationId`, then `controlType` + `name`. Returns `null` if not found. |
+| `Execute(step, resolvedElement)` | Step object, resolved native element | Step result (pass/fail) | Performs the step action on the resolved element. For `invoke`: activates/clicks. For `setValue`: sets the text/value. For `settle`: waits until timeout or condition met. For `capture`: delegates to `Capture()`. |
+| `Capture(name, outputDir)` | Screenshot name, output directory path | File path of saved screenshot | Takes a screenshot of the application window and saves it as `{outputDir}/{name}.png`. |
+| `Report(results)` | Array of step results | Execution summary | Outputs the full execution results: pass/fail per step, screenshots captured with paths, errors with messages and selectors, total duration. |
+
+### Platform-Specific Notes
+
+**Windows: PowerShell + System.Windows.Automation**
+
+```powershell
+# Load the UIA assembly
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+
+# Element resolution using PropertyCondition
+$condition = New-Object System.Windows.Automation.PropertyCondition(
+    [System.Windows.Automation.AutomationElement]::AutomationIdProperty,
+    "loginButton"
+)
+$element = $rootElement.FindFirst(
+    [System.Windows.Automation.TreeScope]::Descendants,
+    $condition
+)
+
+# Invoke action using InvokePattern
+$invokePattern = $element.GetCurrentPattern(
+    [System.Windows.Automation.InvokePattern]::Pattern
+)
+$invokePattern.Invoke()
+
+# SetValue action using ValuePattern
+$valuePattern = $element.GetCurrentPattern(
+    [System.Windows.Automation.ValuePattern]::Pattern
+)
+$valuePattern.SetValue("testuser@example.com")
+```
+
+**macOS: AppleScript/Swift + NSAccessibility**
+
+```applescript
+-- Element resolution using accessibility identifier
+tell application "System Events"
+    tell process "MyApp"
+        set targetElement to first text field whose value of attribute "AXIdentifier" is "usernameInput"
+    end tell
+end tell
+
+-- Invoke action (AXPress)
+tell application "System Events"
+    tell process "MyApp"
+        click button "Login" of window 1
+    end tell
+end tell
+
+-- SetValue action (AXValue)
+tell application "System Events"
+    tell process "MyApp"
+        set value of text field "usernameInput" of window 1 to "testuser@example.com"
+    end tell
+end tell
+```
+
+For programmatic access, use `osascript -e '...'` to execute AppleScript from shell scripts, or use Swift with the `AXUIElement` API for more complex resolution logic.
+
+### Dry-Run Mode
+
+Every platform runner must support a `--dry-run` flag that validates the journey without executing actions:
+
+1. **Load** -- Parse the manifest (same as normal mode)
+2. **Resolve** -- Attempt to find every element referenced in all journey steps. Report which selectors resolved and which failed.
+3. **Skip Execute** -- Do not perform any invoke, setValue, or settle actions
+4. **Skip Capture** -- Do not take screenshots
+5. **Report** -- Output a validation summary: total selectors, resolved count, failed count, failed selector details
+
+Dry-run mode is used during the spike phase to validate that the journey manifest's selectors match the actual application's accessibility tree before committing to a full execution run.
+
+## Journey Manifest Schema
+
+The `journey-manifest.json` file is the top-level manifest that contains all journey definitions, custom mappings, and capture configuration for a project.
+
+### Complete Schema
+
+```json
+{
+  "$schema": "journey-manifest-v1",
+  "generatedBy": "arn-spark-visual-test-engineer",
+  "generatedAt": "2026-02-28T14:30:00Z",
+  "journeys": [
+    {
+      "name": "login-flow",
+      "description": "Tests the login sequence from initial screen through dashboard load",
+      "preconditions": [
+        "Application is running and showing the main window",
+        "No user is currently logged in"
+      ],
+      "steps": [
+        { "type": "capture", "name": "login-screen" },
+        {
+          "type": "setValue",
+          "target": { "automationId": "usernameInput", "controlType": "textBox" },
+          "value": "testuser@example.com"
+        },
+        {
+          "type": "setValue",
+          "target": { "automationId": "passwordInput", "controlType": "textBox" },
+          "value": "test-password-123"
+        },
+        {
+          "type": "invoke",
+          "target": { "automationId": "loginButton", "controlType": "button" },
+          "delay": 200
+        },
+        {
+          "type": "settle",
+          "timeout": 10000,
+          "condition": "Loading spinner disappears and dashboard content is visible"
+        },
+        { "type": "capture", "name": "dashboard-after-login" }
+      ]
+    },
+    {
+      "name": "settings-navigation",
+      "description": "Opens settings from the dashboard and captures each settings panel",
+      "preconditions": [
+        "User is logged in and on the dashboard"
+      ],
+      "steps": [
+        {
+          "type": "invoke",
+          "target": { "automationId": "settingsButton", "controlType": "button" }
+        },
+        {
+          "type": "settle",
+          "timeout": 3000,
+          "condition": "Settings panel is fully loaded"
+        },
+        { "type": "capture", "name": "settings-general" },
+        {
+          "type": "invoke",
+          "target": { "automationId": "appearanceTab", "controlType": "tab" }
+        },
+        {
+          "type": "settle",
+          "timeout": 2000
+        },
+        { "type": "capture", "name": "settings-appearance" }
+      ]
+    }
+  ],
+  "customMappings": {
+    "main-navigation": {
+      "windows": {
+        "automationId": "NavHost",
+        "controlType": "Pane",
+        "className": "NavigationView"
+      },
+      "macos": {
+        "role": "AXGroup",
+        "subrole": "AXNavigationBar",
+        "identifier": "MainNavigation"
+      }
+    }
+  },
+  "captureConfig": {
+    "outputDir": "visual-tests/baselines/layer-2/journeys/",
+    "format": "png",
+    "fullWindow": true
+  }
+}
+```
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `$schema` | string | Yes | Schema version identifier. Must be `"journey-manifest-v1"`. |
+| `generatedBy` | string | Yes | The tool that generated the manifest. Typically `"arn-spark-visual-test-engineer"`. |
+| `generatedAt` | string | Yes | ISO 8601 timestamp of when the manifest was generated. |
+| `journeys` | array | Yes | Array of journey objects. Each journey defines a complete user interaction flow. |
+| `journeys[].name` | string | Yes | Unique identifier for the journey. Used in reporting and file organization. |
+| `journeys[].description` | string | Yes | Human-readable description of what the journey tests. |
+| `journeys[].preconditions` | array | Yes | List of application state requirements that must be true before the journey starts. |
+| `journeys[].steps` | array | Yes | Ordered array of step objects. Each step is one of: `capture`, `invoke`, `setValue`, `settle`. |
+| `customMappings` | object | No | Maps logical component names to platform-specific selectors. See Custom Mappings section. |
+| `captureConfig` | object | Yes | Configuration for screenshot capture. |
+| `captureConfig.outputDir` | string | Yes | Directory where captured screenshots are saved. Relative to project root. |
+| `captureConfig.format` | string | Yes | Image format for captures. Must be `"png"`. |
+| `captureConfig.fullWindow` | boolean | Yes | Whether to capture the full application window (`true`) or just the client area (`false`). |

package/plugins/arn-spark/skills/arn-spark-visual-strategy/references/spike-checklist.md

@@ -0,0 +1,122 @@
+# Visual Strategy Spike Checklist
+
+Validation criteria used by `arn-spark-visual-strategy` when running mini-spikes to validate each testing layer. The skill reads this checklist and applies the relevant layer's criteria during Step 4 (Validate Strategy with Mini-Spike).
+
+## Layer 1: Browser-Based Capture (Playwright)
+
+### Prerequisites
+- [ ] Node.js available in the environment
+- [ ] Playwright installable (`npm install -D @playwright/test`)
+- [ ] Dev server starts and responds at the expected URL
+
+### Capture Validation
+- [ ] At least one screenshot captured successfully
+- [ ] Screenshot is at the configured viewport size (check image dimensions)
+- [ ] Screenshot content matches the expected screen (not a blank page, error page, or loading spinner)
+- [ ] Multiple screens captured without navigation errors
+- [ ] Screenshots saved to the configured output directory with correct naming
+
+### Comparison Validation
+- [ ] Diff tool (pixelmatch/looks-same) installs and runs
+- [ ] Comparing identical images produces a 0% diff (or below threshold)
+- [ ] Comparing intentionally different images produces a detectable diff above threshold
+- [ ] Diff output is human-readable (diff image or percentage report)
+
+### Headless Validation
+- [ ] Capture script runs in headless mode (no display server required)
+- [ ] Headless screenshots match headed screenshots (no rendering differences)
+
+### Dark Mode (if applicable)
+- [ ] Dark mode toggle mechanism works in Playwright
+- [ ] Dark mode screenshots captured alongside light mode
+- [ ] Dark mode screenshots show correct dark theme (not just light mode duplicated)
+
+## Layer 2: Native Application Capture
+
+### Prerequisites
+- [ ] Application builds successfully on the target OS
+- [ ] Built application launches and displays the main window
+- [ ] Screenshot capture tool is available (platform-specific)
+
+### Build Validation
+- [ ] Build command completes without errors
+- [ ] Build output exists at the expected path
+- [ ] Build output is executable/launchable
+
+### Capture Validation
+- [ ] Screenshot captured of the running application window
+- [ ] Screenshot resolution is correct (matches display/window size)
+- [ ] Screenshot includes native window chrome (title bar, borders)
+- [ ] Transparency effects visible in screenshot (if applicable)
+- [ ] Application window identified correctly (not capturing wrong window)
+
+### Cross-Environment Validation (WSL2 to Windows, etc.)
+- [ ] File transfer from dev environment to target OS works (e.g., WSL2 -> /mnt/c/...)
+- [ ] Build command runs on target OS from the transferred files
+- [ ] Screenshot capture runs on target OS
+- [ ] Screenshot files transferred back to dev environment
+- [ ] Diff comparison runs on dev environment with the captured screenshots
+
+## Layer 2 -- Journey Interaction
+
+> Validate only when `Interaction: journey` is selected for Layer 2. These checks extend the standard Layer 2 checklist above.
+
+### Prerequisites
+
+- [ ] UIA framework available — Windows: `Add-Type -AssemblyName UIAutomationClient` loads successfully; macOS: `osascript` can query accessibility tree
+- [ ] Accessibility tree inspectable — can enumerate UI elements of the target application
+- [ ] Automation IDs present — key interactive elements (buttons, inputs, menus) have automation IDs assigned
+- [ ] Journey manifest exists — `journey-manifest.json` has been generated by `arn-spark-visual-test-engineer`
+- [ ] Runner script exists — platform-specific runner script has been generated
+
+### Journey Execution
+
+- [ ] Runner loads journey manifest without errors
+- [ ] Runner resolves element selectors (automationId, controlType, name) for all journey steps
+- [ ] Runner executes steps in order (invoke, setValue, settle, capture)
+- [ ] Capture steps produce screenshots at the correct resolution
+- [ ] Complete journey runs end-to-end without crashes or unhandled errors
+
+### Interaction Validation
+
+- [ ] `invoke` steps click the correct elements (verify via visible state change)
+- [ ] `setValue` steps populate input fields with the specified values (verify via reading the value back)
+- [ ] `settle` steps wait appropriately (page loads complete, animations finish, spinners disappear)
+- [ ] State transitions are visible in captured screenshots (e.g., login form → dashboard)
+
+### macOS Permissions
+
+- [ ] Terminal/IDE has Accessibility permission granted (System Preferences > Privacy & Security > Accessibility)
+- [ ] `osascript` accessibility queries succeed without authorization errors
+- [ ] If permission is not granted, agent prompts user with step-by-step instructions before retrying
+
+### Custom Mapping Validation
+
+- [ ] At least one custom mapping resolves correctly on the target platform
+- [ ] Platform-specific selectors (windows/macos) in custom mappings match actual accessibility tree elements
+- [ ] Mapped elements are interactable (can be invoked, can receive values)
+- [ ] Fallback to automationId works when custom mapping is not defined for an element
+
+## Layer 3: Extended Validation
+
+### Mobile Viewport (if applicable)
+- [ ] Playwright mobile device emulation configured
+- [ ] Screenshots captured at mobile viewport sizes
+- [ ] Touch interactions simulated where relevant
+- [ ] Responsive layout changes visible in captures
+
+### CI Integration (if applicable)
+- [ ] CI workflow file is valid YAML
+- [ ] Visual test step runs in the CI pipeline
+- [ ] Screenshots uploaded as CI artifacts
+- [ ] Diff results reported in CI output
+- [ ] Failure (visual regression detected) causes CI step to fail
+
+## Spike Result Classification
+
+| Result | Criteria |
+|--------|----------|
+| **Validated** | All prerequisite checks pass AND at least capture + comparison validation pass |
+| **Partially validated** | Prerequisites pass, capture works, but comparison has caveats (e.g., anti-aliasing noise) |
+| **Failed** | Prerequisites fail OR capture does not produce usable screenshots |
+| **Deferred** | Cannot be validated in the current environment (e.g., WSL2 cannot run native Windows capture). Scripts created for manual validation on target OS. |

package/plugins/arn-spark/skills/arn-spark-visual-strategy/references/strategy-layers-guide.md

@@ -0,0 +1,132 @@
+# Strategy Layers Guide
+
+This guide helps `arn-spark-visual-strategy` recommend appropriate visual testing layers based on the project's application type, rendering context, and development environment. Each layer represents a testing approach with different coverage, complexity, and infrastructure requirements.
+
+## Layer Decision Matrix
+
+| App Type | Rendering Context | Layer 1 (Recommended) | Layer 2 (Optional) | Layer 3 (Advanced) |
+|----------|-------------------|----------------------|--------------------|--------------------|
+| Pure browser SPA | Browser viewport | Playwright against dev server | Mobile viewport emulation (Playwright devices) | Real device testing (BrowserStack / Sauce Labs) |
+| SSR web app (Next.js, Nuxt, SvelteKit) | Browser viewport | Playwright against dev server | Mobile viewport + SSR snapshot testing | Real device testing |
+| Tauri (no transparency) | Webview in native frame | Playwright against dev server (web content) | Tauri CLI build + OS-native screenshot on target OS | CI matrix with per-OS capture |
+| Tauri (with transparency) | Native window with compositor | Playwright against dev server (web content only) | Cross-environment build + native screenshot (e.g., WSL2->Windows) | Per-OS CI runners with display server |
+| Electron | Chromium webview | Playwright against dev server | Electron `BrowserWindow.capturePage()` API | CI matrix with per-OS capture |
+| React Native (web) | Browser viewport | Playwright against dev server | Mobile emulator screenshots (Android Studio / Xcode Simulator) | Real device testing |
+| Progressive Web App | Browser viewport | Playwright against dev server | Mobile viewport + installable PWA testing | Lighthouse visual audits |
+
+## Layer Definitions
+
+### Layer 1: Browser-Based Capture (Playwright)
+
+**What:** Run the project's dev server, connect Playwright (headless Chromium), navigate to each screen/route, capture screenshots at a configured viewport size.
+
+**Captures:** All web UI content — layouts, component rendering, typography, colors, spacing, responsive behavior, hover/focus states (via Playwright interactions).
+
+**Does NOT capture:** Native window chrome, OS-level transparency/compositing, system tray icons, notification popups, platform-specific font rendering differences.
+
+**Requirements:**
+- Node.js runtime
+- Playwright (`npm install -D @playwright/test`)
+- Dev server that serves the web content (e.g., `npm run dev`)
+
+**Environment:** Runs anywhere Node.js runs. Works in WSL2, CI runners, Docker containers (with `--no-sandbox`), macOS, Linux, Windows. Headless mode requires no display server.
+
+**When to use:** Always. This is the default first layer for any project with web-based UI. It catches the majority of visual regressions (layout shifts, component styling, color changes, text rendering).
+
+### Layer 2: Native Application Capture
+
+**What:** Build the full application (not just the web content), run it on the target OS, capture a screenshot of the actual application window as rendered by the OS compositor.
+
+**Captures:** Everything visible on screen including native window chrome, transparency effects, blur layers, system integration, platform-specific rendering.
+
+**Does NOT capture:** Dynamic OS state (notifications from other apps, wallpaper bleeding through transparency), GPU-specific rendering artifacts.
+
+**Interaction mode:**
+
+Layer 2 supports two interaction modes:
+
+| Mode | Description | Requirements |
+|------|-------------|-------------|
+| `static` | Captures predefined screens without user interaction (current default behavior) | Platform access, capture script |
+| `journey` | Walks through the app using ordered step sequences via OS accessibility APIs (UIA / NSAccessibility), capturing screenshots at checkpoints | UIA/NSAccessibility tooling, automation IDs, journey manifest, runner script |
+
+Journey mode uses the platform's native UI automation API to simulate real user flows — clicking buttons, filling forms, navigating between screens — and captures screenshots at each checkpoint step. This enables visual regression detection for state transitions, form validation feedback, navigation flows, and dynamic content that static capture cannot test.
+
+Journey mode requirements:
+- Platform automation framework available (Windows UIA or macOS NSAccessibility)
+- Target application exposes automation IDs on interactive elements
+- Journey manifest (`journey-manifest.json`) defining the step sequences
+- Platform-specific runner script generated by `arn-spark-visual-test-engineer`
+
+> See `journey-schema.md` in this directory for the complete journey definition schema, element selector format, custom mappings, and platform runner contract.
+
+When no `**Interaction:**` field is present in the Layer 2 config, the default is `static` (backward compatible).
+
+**Requirements vary by app type:**
+
+| App Type | Build Command | Capture Method | OS Requirement |
+|----------|--------------|----------------|----------------|
+| Tauri (Windows) | `cargo tauri build` | PowerShell screen capture script or Nircmd screenshot | Windows 10/11 |
+| Tauri (macOS) | `cargo tauri build` | `screencapture -l <window_id>` | macOS with Xcode |
+| Tauri (Linux) | `cargo tauri build` | `xdotool` + `import` (ImageMagick) or `gnome-screenshot` | Linux with X11/Wayland |
+| Electron | `npm run build` | `BrowserWindow.capturePage()` in test harness | Any (Electron bundles Chromium) |
+
+**Cross-Environment Patterns:**
+
+**WSL2 to Windows (Tauri):**
+1. Copy project source to a Windows-accessible path (`/mnt/c/Users/.../project`)
+2. Run `cargo tauri build` from Windows (PowerShell or CMD)
+3. Launch the built executable on Windows
+4. Capture screenshot using Windows screenshot tool
+5. Copy screenshot back to WSL2 (`/mnt/c/...` -> project directory)
+6. Run diff comparison on WSL2
+
+**CI with OS Matrix:**
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, windows-latest, macos-latest]
+steps:
+  - uses: actions/checkout@v4
+  - name: Build application
+    run: [build command]
+  - name: Capture screenshots
+    run: [platform-specific capture]
+  - uses: actions/upload-artifact@v4
+    with:
+      name: visual-captures-${{ matrix.os }}
+      path: visual-tests/captures/
+```
+
+### Layer 3: Extended Validation
+
+Advanced testing approaches for specific needs. Typically added later in the project lifecycle.
+
+- **Real device testing** (BrowserStack, Sauce Labs): For mobile apps or cross-browser validation
+- **Accessibility visual testing**: High-contrast mode, reduced motion, screen magnification
+- **Performance visual testing**: Capture at different network speeds, measure visual stability (CLS)
+
+## Comparison Tool Options
+
+| Tool | Language | Method | Strengths | Weaknesses |
+|------|----------|--------|-----------|------------|
+| pixelmatch | JS | Pixel-by-pixel RGB diff | Fast, lightweight, zero deps | Sensitive to anti-aliasing |
+| looks-same | JS | Perceptual diff with anti-aliasing tolerance | Handles sub-pixel rendering well | Slower than pixelmatch |
+| reg-suit | JS | Full visual regression framework | CI integration, report generation | Heavier setup |
+| BackstopJS | JS | Playwright + resemblejs | Scenario-based, config-driven | Opinionated structure |
+| Percy (commercial) | SaaS | Cloud-based visual review | Handles cross-browser, team review | Requires account, costs money |
+
+**Recommendation:** Start with `pixelmatch` for simplicity. If anti-aliasing noise is a problem (common with text rendering), switch to `looks-same` with tolerance configuration.
+
+## Threshold Guidelines
+
+| Content Type | Recommended Threshold | Rationale |
+|-------------|----------------------|-----------|
+| Layout-heavy screens | 0.1% | Layout shifts are obvious even at low pixel counts |
+| Text-heavy screens | 0.5% | Sub-pixel font rendering varies across environments |
+| Image/gradient screens | 1.0% | Compression and rendering engine differences |
+| Transparency/blur effects | 2.0% | Compositor-dependent rendering |
+| Journey captures (interaction-dependent states) | 2-5% | State transitions introduce timing-dependent rendering variation |
+| Cross-layer comparison (Layer 1 vs Layer 2) | 5-10% | Different rendering engines (browser vs native) produce expected differences |
+
+These are starting points. Adjust per-screen based on spike results.