@qa-gentic/agents 1.1.2

package/src/qa_stlc_agents/agent_playwright_generator/server.py

@@ -0,0 +1,2771 @@
+"""
+Agent 3: QA Playwright Code Generator — MCP Server
+
+Browser interaction at generation time is handled by the external Playwright MCP
+server (github.com/microsoft/playwright-mcp). Start it before running workflows:
+    npx @playwright/mcp@latest --port 8931
+
+The coding agent uses Playwright MCP tools (browser_navigate, browser_snapshot,
+browser_fill, browser_click, browser_wait_for_url) to build a verified context_map
+of locators from the live accessibility tree, then passes that map to
+generate_playwright_code.
+
+Three layers of self-healing at TEST RUNTIME:
+  1. Locator Healing    — selector chain + AI Vision
+  2. Timing Healing     — network trace drift detection → auto-adjusted timeouts
+  3. Visual Regression  — element screenshot diff against approved baseline
+
+DevToolsHealer (Layer 4) runs at test runtime via Playwright's built-in CDPSession —
+no external process or port required.
+
+CI/CD Telemetry:
+  HealingDashboard — HTTP server on :7890, engineers review/approve AI suggestions
+  before they are permanently committed to the repository.
+"""
+from __future__ import annotations
+import asyncio, json, re, sys, os
+from pathlib import Path
+from dotenv import load_dotenv
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp import types
+from qa_stlc_agents.shared.auth import get_auth_headers, get_signed_in_user
+from qa_stlc_agents.agent_playwright_generator.tools.ado_attach import attach_file_to_work_item as _attach_file
+
+load_dotenv()
+app = Server("qa-playwright-generator")
+
+
+# ---------------------------------------------------------------------------
+# Pre-output validation helpers
+# ---------------------------------------------------------------------------
+
+def _validate_scaffold_output(result: dict) -> dict:
+    """Validate scaffold_locator_repository output before returning to user.
+
+    Checks:
+      1. All expected infrastructure files are present.
+      2. File contents are non-empty.
+      3. Basic TS syntax (brace/paren balance) for each file.
+
+    Returns { valid: bool, errors: list[str], warnings: list[str] }.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    files = result.get("files", {})
+    if not files:
+        errors.append("scaffold_locator_repository produced no files.")
+        return {"valid": False, "errors": errors, "warnings": warnings}
+
+    required_bases = {"LocatorHealer.ts", "LocatorRepository.ts"}
+    found_bases = {Path(k).name for k in files}
+    missing = required_bases - found_bases
+    if missing:
+        errors.append(f"Missing required infrastructure files: {sorted(missing)}")
+
+    for file_key, content in files.items():
+        if not content or not content.strip():
+            errors.append(f"{file_key}: file content is empty.")
+            continue
+        # Brace/paren balance
+        s = re.sub(r'`[^`]*`', '``', content)
+        s = re.sub(r'"[^"\n]*"', '""', s)
+        s = re.sub(r"'[^'\n]*'", "''", s)
+        s = re.sub(r'//[^\n]*', '', s)
+        s = re.sub(r'/\*.*?\*/', '', s, flags=re.DOTALL)
+        brace_delta = s.count('{') - s.count('}')
+        if brace_delta != 0:
+            errors.append(f"{file_key}: unbalanced braces (delta={brace_delta:+d})")
+        paren_delta = s.count('(') - s.count(')')
+        if paren_delta != 0:
+            errors.append(f"{file_key}: unbalanced parentheses (delta={paren_delta:+d})")
+
+    return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+
+def _validate_attach_inputs(files: list[dict]) -> dict:
+    """Validate file payloads before attaching to ADO.
+
+    Checks:
+      1. Files list is non-empty.
+      2. Every file has a non-empty file_name and content.
+      3. No duplicate file names.
+      4. File names use safe characters.
+
+    Returns { valid: bool, errors: list[str], warnings: list[str] }.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not files:
+        errors.append("No files to attach. Provide at least one file.")
+        return {"valid": False, "errors": errors, "warnings": warnings}
+
+    seen_names: set[str] = set()
+    for i, f in enumerate(files, start=1):
+        name = (f.get("file_name") or "").strip()
+        content = (f.get("content") or "").strip()
+
+        if not name:
+            errors.append(f"File #{i}: file_name is empty or missing.")
+        elif name in seen_names:
+            errors.append(f"File #{i}: duplicate file_name '{name}'.")
+        else:
+            seen_names.add(name)
+
+        if not content:
+            errors.append(f"File #{i} ('{name}'): content is empty.")
+
+        # Check for unsafe characters in filename
+        if name and re.search(r'[<>:"|?*\\]', name):
+            warnings.append(
+                f"File #{i} ('{name}'): file name contains characters that may be "
+                f"problematic on some file systems."
+            )
+
+    return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+@app.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="generate_playwright_code",
+            description=(
+                "Generate complete Playwright TypeScript code from a Gherkin .feature file. "
+                "Produces: locators.ts (selector+intent+stability+visualIntent), "
+                "{Page}Page.ts (LocatorHealer + TimingHealer + VisualIntentChecker), "
+                "{feature}.steps.ts, {feature}.feature, cucumber-profile.js. "
+                "All actions go through LocatorHealer (never raw page.click/fill). "
+                "TimingHealer intercepts network traces per action. "
+                "VisualIntentChecker screenshots elements at key assertions. "
+                "Pass context_map from Playwright MCP browser_snapshot calls to use "
+                "accessibility-tree-verified selectors instead of Gherkin inference. "
+                "Pass helix_project_root to auto-merge with existing Helix-QA files "
+                "(no overwrites, deduplication, conflict renaming)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "gherkin_content": {"type": "string"},
+                    "page_class_name": {"type": "string"},
+                    "app_name": {"type": "string"},
+                    "healing_strategy": {
+                        "type": "string",
+                        "enum": ["role-label-text-ai", "role-text-ai", "ai-first"],
+                    },
+                    "auth_hook": {
+                        "type": "string",
+                        "enum": ["microsoft-sso", "azure-keyvault-mfa", "none"],
+                    },
+                    "enable_visual_regression": {"type": "boolean"},
+                    "enable_timing_healing": {"type": "boolean"},
+                    "context_map": {
+                        "type": "object",
+                        "description": (
+                            "Verified locator map built from Playwright MCP browser_snapshot calls. "
+                            "Each key maps to { selector, intent, stability, visualIntent? }. "
+                            "When provided, overrides Gherkin-inferred selectors. "
+                            "Build by: browser_navigate → browser_snapshot → map AX nodes to entries "
+                            "using stability rank: data-testid(100) > aria-role+name(90) > id(80) "
+                            "> aria-label(70) > placeholder(60)."
+                        ),
+                    },
+                    "helix_project_root": {
+                        "type": "string",
+                        "description": (
+                            "Optional path to Helix-QA project root. When provided, generated code "
+                            "is merged with existing files (append-only, deduplication, conflict renaming). "
+                            "No overwrites ever occur. Locators with naming conflicts get unique names. "
+                            "Pass this to enable seamless integration with your automation framework."
+                        ),
+                    },
+                },
+                "required": ["gherkin_content", "page_class_name"],
+            },
+        ),
+        types.Tool(
+            name="scaffold_locator_repository",
+            description=(
+                "Generate the complete self-healing infrastructure. Six files: "
+                "LocatorHealer.ts, LocatorRepository.ts, "
+                "TimingHealer.ts (network trace timing healing — observes API response times, "
+                "auto-adjusts timeouts when endpoints drift beyond 20% of baseline), "
+                "VisualIntentChecker.ts (screenshot-based visual regression at key assertions — "
+                "detects elements that are found but look wrong), "
+                "DevToolsHealer.ts (CDP healing via Playwright CDPSession at test runtime — "
+                "AX tree name match + bounding box spatial search, no external process needed), "
+                "HealingDashboard.ts (HTTP server on :7890 — shows all pending AI suggestions "
+                "from all three layers; engineers approve/reject before changes are committed). "
+                "Call once per project."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "output_dir": {"type": "string"},
+                    "enable_ai_vision": {"type": "boolean"},
+                    "repository_path": {"type": "string"},
+                    "dashboard_port": {"type": "integer"},
+                    "enable_timing_healing": {"type": "boolean"},
+                    "enable_visual_regression": {"type": "boolean"},
+                    "enable_devtools_healer": {"type": "boolean"},
+                    "ai_healing_provider": {
+                        "type": "string",
+                        "enum": ["anthropic", "copilot", "claude-code"],
+                        "description": (
+                            "AI Vision provider for strategy 6 healing. "
+                            "anthropic: direct Anthropic API (requires AI_HEALING_API_KEY env var). "
+                            "copilot: GitHub Copilot chat completions (uses GITHUB_TOKEN from Copilot extension or gh auth login). "
+                            "claude-code: Claude Code local proxy (uses ANTHROPIC_API_KEY set automatically by the claude CLI session). "
+                            "Can also be overridden at runtime via the AI_HEALING_PROVIDER env var without regenerating files. "
+                            "Default: anthropic."
+                        ),
+                    },
+                },
+                "required": [],
+            },
+        ),
+        types.Tool(
+            name="attach_code_to_work_item",
+            description=(
+                "Attach generated TypeScript files to an ADO work item (Feature, PBI, or Bug). "
+                "NEVER pass an Epic ID — attachments on Epics are invisible in normal ADO workflow "
+                "views. If you have an Epic ID, use qa-gherkin-generator:fetch_epic_hierarchy "
+                "to walk its child Features and PBIs/Bugs, then call this tool once per Feature "
+                "or PBI/Bug work item ID."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "organization_url": {"type": "string"},
+                    "project_name": {"type": "string"},
+                    "work_item_id": {"type": "integer"},
+                    "files": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "file_name": {"type": "string"},
+                                "content": {"type": "string"},
+                            },
+                            "required": ["file_name", "content"],
+                        },
+                    },
+                },
+                "required": ["organization_url", "project_name", "work_item_id", "files"],
+            },
+        ),
+        types.Tool(
+            name="validate_gherkin_steps",
+            description="Parse a .feature file and return all unique step strings grouped by keyword.",
+            inputSchema={
+                "type": "object",
+                "properties": {"gherkin_content": {"type": "string"}},
+                "required": ["gherkin_content"],
+            },
+        ),
+        types.Tool(
+            name="pre_validate_cucumber_steps",
+            description=(
+                "Validate Cucumber step syntax in TypeScript step-definition files BEFORE passing "
+                "them to write_helix_files. Catches issues that cause the parenthesis-balance "
+                "validator to fail and blocks write_helix_files submissions containing bad patterns.\n\n"
+                "Checks performed:\n"
+                "  1. Raw regex step patterns (/^…$/) with unescaped capture groups — these "
+                "unbalance the paren counter. Prescribes Cucumber expression replacements.\n"
+                "  2. Step patterns that mix Cucumber expressions and regex syntax.\n"
+                "  3. Missing closing parenthesis or brace in step callback functions.\n"
+                "  4. Duplicate step patterns within the same file.\n"
+                "  5. Gherkin feature steps that have no matching step definition (unmatched steps).\n\n"
+                "Returns { valid: bool, errors: list, warnings: list, suggestions: list } "
+                "where suggestions provide ready-to-paste Cucumber expression replacements for "
+                "every flagged raw-regex pattern. Fix all errors before calling write_helix_files."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "steps_ts_content": {
+                        "type": "string",
+                        "description": (
+                            "Content of the generated *.steps.ts file to validate. "
+                            "Pass the value from generate_playwright_code['files']['<feature>.steps.ts']."
+                        ),
+                    },
+                    "gherkin_content": {
+                        "type": "string",
+                        "description": (
+                            "Optional: content of the .feature file. "
+                            "When provided, enables unmatched-step detection (check 5)."
+                        ),
+                    },
+                },
+                "required": ["steps_ts_content"],
+            },
+        ),
+    ]
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    try:
+        if name == "generate_playwright_code":
+            result = await asyncio.to_thread(
+                _generate_playwright_code,
+                arguments["gherkin_content"],
+                arguments["page_class_name"],
+                arguments.get("app_name", "app"),
+                arguments.get("healing_strategy", "role-label-text-ai"),
+                arguments.get("auth_hook", "microsoft-sso"),
+                arguments.get("enable_visual_regression", True),
+                arguments.get("enable_timing_healing", True),
+                arguments.get("context_map"),
+                arguments.get("helix_project_root"),
+            )
+        elif name == "scaffold_locator_repository":
+            result = await asyncio.to_thread(
+                _scaffold_locator_repository,
+                arguments.get("output_dir", "src/utils/locators"),
+                arguments.get("enable_ai_vision", True),
+                arguments.get("repository_path", "test-results/locator-repository.json"),
+                arguments.get("dashboard_port", 7890),
+                arguments.get("enable_timing_healing", True),
+                arguments.get("enable_visual_regression", True),
+                arguments.get("enable_devtools_healer", True),
+                arguments.get("ai_healing_provider", "anthropic"),
+            )
+            # ── Pre-output validation ─────────────────────────────────────
+            result["_validation"] = _validate_scaffold_output(result)
+        elif name == "attach_code_to_work_item":
+            # ── Pre-attach input validation ────────────────────────────────
+            input_validation = _validate_attach_inputs(arguments.get("files", []))
+            if not input_validation["valid"]:
+                result = {
+                    "error": "input_validation_failed",
+                    "_validation": input_validation,
+                    "message": (
+                        "File inputs failed validation. Fix the errors below "
+                        "and retry. No files were attached to ADO."
+                    ),
+                }
+                return [types.TextContent(type="text", text=json.dumps(result, indent=2, ensure_ascii=False))]
+
+            # ── Epic guard — attachments on Epics are invisible in ADO workflow views ──
+            wi_id = arguments["work_item_id"]
+            try:
+                import requests as _requests
+                from qa_stlc_agents.shared.auth import get_auth_headers as _gah
+                _peek = await asyncio.to_thread(
+                    lambda: _requests.get(
+                        f"{arguments['organization_url'].rstrip('/')}/{arguments['project_name']}"
+                        f"/_apis/wit/workitems/{wi_id}",
+                        headers=_gah(),
+                        params={"api-version": "7.1"},
+                        timeout=15,
+                    )
+                )
+                if _peek.ok:
+                    _wi_type = _peek.json().get("fields", {}).get("System.WorkItemType", "")
+                    if _wi_type == "Epic":
+                        return [types.TextContent(type="text", text=json.dumps({
+                            "error": "epic_not_supported",
+                            "work_item_id": wi_id,
+                            "work_item_type": "Epic",
+                            "message": (
+                                f"Work item {wi_id} is an Epic. Playwright TypeScript files "
+                                "must NOT be attached directly to an Epic — attachments on Epics "
+                                "are effectively invisible in normal ADO workflow views. "
+                                "Use qa-gherkin-generator:fetch_epic_hierarchy to walk the child "
+                                "Features and PBIs/Bugs, then call attach_code_to_work_item once "
+                                "per Feature or PBI/Bug work item ID."
+                            ),
+                        }, indent=2))]
+            except Exception:
+                pass  # If the peek fails, let the attach proceed and surface any real error naturally
+
+            attached, failed = [], []
+            for f in arguments["files"]:
+                try:
+                    r = await asyncio.to_thread(
+                        _attach_file,
+                        arguments["organization_url"], arguments["project_name"],
+                        arguments["work_item_id"], f["file_name"], f["content"],
+                        "Generated by QA Playwright Code Generator",
+                    )
+                    attached.append(r)
+                except Exception as e:
+                    failed.append({"file_name": f["file_name"], "error": str(e)})
+            result = {
+                "summary": {"requested": len(arguments["files"]),
+                            "attached": len(attached), "failed": len(failed)},
+                "attached": attached, "failed": failed,
+                "_validation": {
+                    "valid": len(failed) == 0,
+                    "errors": [f["error"] for f in failed] if failed else [],
+                    "warnings": input_validation.get("warnings", []),
+                    "post_attach_check": {
+                        "all_attached": len(attached) == len(arguments["files"]),
+                        "failed_count": len(failed),
+                    },
+                },
+            }
+        elif name == "validate_gherkin_steps":
+            result = await asyncio.to_thread(_parse_gherkin_steps, arguments["gherkin_content"])
+        elif name == "pre_validate_cucumber_steps":
+            result = await asyncio.to_thread(
+                _pre_validate_cucumber_steps,
+                arguments["steps_ts_content"],
+                arguments.get("gherkin_content"),
+            )
+        else:
+            result = {"error": f"Unknown tool: {name}"}
+        return [types.TextContent(type="text", text=json.dumps(result, indent=2, ensure_ascii=False))]
+    except Exception as exc:
+        return [types.TextContent(type="text", text=json.dumps({"error": str(exc), "tool": name}, indent=2))]
+
+
+# ============================================================================
+# Core helpers
+# ============================================================================
+
+def _to_kebab(s: str) -> str:
+    s = re.sub(r"([A-Z])", r"-\1", s).lower().strip("-")
+    return re.sub(r"-+", "-", s)
+
+
+def _parse_gherkin_steps(content: str) -> dict:
+    keywords = ("Given", "When", "Then", "And", "But")
+    steps: dict = {k: [] for k in keywords}
+    for line in content.splitlines():
+        stripped = line.strip()
+        for kw in keywords:
+            if stripped.startswith(kw + " "):
+                text = stripped[len(kw):].strip()
+                if text not in steps[kw]:
+                    steps[kw].append(text)
+                break
+    all_steps = [f"{kw} {s}" for kw in keywords for s in steps[kw]]
+    return {"by_keyword": steps, "all_steps": all_steps, "total_unique_steps": len(all_steps)}
+
+
+# Cucumber expression parameter types — any of these in a step pattern means
+# the step already uses Cucumber expressions correctly.
+_CUCUMBER_EXPR_RE = re.compile(r"\{(?:string|int|float|word|bigdecimal|byte|short|long|double|[A-Za-z_]\w*)\}")
+
+# Regex step pattern: Given(/^…$/, …) or When(/^…$/, …)
+_RAW_REGEX_STEP_RE = re.compile(
+    r"^(Given|When|Then)\s*\(\s*/\^([^$]*)\$\s*/[gimusy]*\s*,",
+    re.MULTILINE,
+)
+
+# Capture groups inside a regex pattern that should become Cucumber expressions
+_CAPTURE_GROUP_RE = re.compile(r"\((?!\?)")  # ( not followed by ? (i.e. not (?:) or (?=) etc.)
+
+# Mapping from common regex fragments to Cucumber expression equivalents
+_REGEX_TO_CUCUMBER: list[tuple[re.Pattern, str]] = [
+    (re.compile(r'\(\.\+\)'),       "{string}"),
+    (re.compile(r'\(\.\*\)'),       "{string}"),
+    (re.compile(r'\(\\d\+\)'),      "{int}"),
+    (re.compile(r'\(\\d\+\\.\\d\+\)'), "{float}"),
+    (re.compile(r'\(\\w\+\)'),      "{word}"),
+    (re.compile(r'\([^)]+\)'),      "{string}"),   # fallback for any other group
+]
+
+
+def _regex_pattern_to_cucumber(raw_pattern: str) -> str:
+    """Best-effort conversion of a raw regex step pattern to a Cucumber expression."""
+    result = raw_pattern
+    for rx, replacement in _REGEX_TO_CUCUMBER:
+        result = rx.sub(replacement, result, count=1)
+        if result != raw_pattern:
+            break
+    # Replace all remaining capture groups with {string}
+    result = _CAPTURE_GROUP_RE.sub("{string}", result)
+    return result
+
+
+def _pre_validate_cucumber_steps(steps_ts_content: str, gherkin_content: str | None) -> dict:
+    """Validate Cucumber step syntax in a generated *.steps.ts file.
+
+    Returns { valid: bool, errors: list[str], warnings: list[str], suggestions: list[dict] }.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    suggestions: list[dict] = []
+
+    if not steps_ts_content or not steps_ts_content.strip():
+        return {
+            "valid": False,
+            "errors": ["steps_ts_content is empty — nothing to validate."],
+            "warnings": [],
+            "suggestions": [],
+        }
+
+    lines = steps_ts_content.splitlines()
+
+    # ── Check 1 & 2: raw regex patterns and mixed syntax ─────────────────
+    seen_patterns: list[str] = []
+    for match in _RAW_REGEX_STEP_RE.finditer(steps_ts_content):
+        keyword, raw_pattern = match.group(1), match.group(2)
+        capture_count = len(_CAPTURE_GROUP_RE.findall(raw_pattern))
+        if capture_count > 0:
+            cucumber_expr = _regex_pattern_to_cucumber(raw_pattern)
+            errors.append(
+                f"{keyword}(/^{raw_pattern}$/) uses a raw regex with {capture_count} "
+                f"capture group(s). "
+                f"The regex preprocessor in write_helix_files strips string literals before "
+                f"counting parentheses, so these unmatched '(' cause the paren-balance check "
+                f"to fail with delta={capture_count:+d}. "
+                f"Fix: replace the regex with a Cucumber expression."
+            )
+            suggestions.append({
+                "original": f"/^{raw_pattern}$/",
+                "replacement": f"'{cucumber_expr}'",
+                "keyword": keyword,
+                "note": (
+                    "Replace the /^…$/ regex with the quoted Cucumber expression. "
+                    "Update the callback parameter types: string for {string}, number for {int}/{float}."
+                ),
+            })
+        elif _CUCUMBER_EXPR_RE.search(raw_pattern):
+            warnings.append(
+                f"{keyword}(/^{raw_pattern}$/) mixes regex anchors with Cucumber expressions. "
+                f"Use either a plain Cucumber expression string OR a pure regex — not both."
+            )
+        seen_patterns.append(raw_pattern)
+
+    # ── Check 3: unbalanced braces / parens in step callbacks ────────────
+    # Strip string literals and comments, then check balance per-block
+    stripped = re.sub(r'`[^`]*`', '``', steps_ts_content)
+    stripped = re.sub(r'"[^"\n]*"', '""', stripped)
+    stripped = re.sub(r"'[^'\n]*'", "''", stripped)
+    stripped = re.sub(r'//[^\n]*', '', stripped)
+    stripped = re.sub(r'/\*.*?\*/', '', stripped, flags=re.DOTALL)
+    # Skip regex literals (/^…$/) so they don't confuse the counter
+    stripped = re.sub(r'/\^[^/]+\$/', '/REGEX/', stripped)
+
+    brace_delta = stripped.count('{') - stripped.count('}')
+    paren_delta = stripped.count('(') - stripped.count(')')
+    if brace_delta != 0:
+        errors.append(
+            f"File-level unbalanced braces (delta={brace_delta:+d}) after stripping "
+            f"string literals and comments. Check for unterminated arrow functions or class bodies."
+        )
+    if paren_delta != 0:
+        # Only flag if no raw-regex errors already explain this
+        if not any("capture group" in e for e in errors):
+            errors.append(
+                f"File-level unbalanced parentheses (delta={paren_delta:+d}) after stripping "
+                f"string literals and comments. This will cause write_helix_files to reject the file. "
+                f"Check for unclosed function calls or raw regex step patterns with capture groups."
+            )
+
+    # ── Check 4: duplicate step patterns ─────────────────────────────────
+    all_patterns: list[str] = []
+    for match in re.finditer(
+        r"(?:Given|When|Then)\s*\(\s*(?:'([^']+)'|\"([^\"]+)\"|/\^([^$]+)\$/)",
+        steps_ts_content,
+    ):
+        pattern = match.group(1) or match.group(2) or match.group(3) or ""
+        if pattern in all_patterns:
+            errors.append(f"Duplicate step pattern: '{pattern}' — defined more than once.")
+        else:
+            all_patterns.append(pattern)
+
+    # ── Check 5: unmatched Gherkin steps (optional) ───────────────────────
+    if gherkin_content:
+        gherkin_parsed = _parse_gherkin_steps(gherkin_content)
+        unmatched: list[str] = []
+        for step_text in gherkin_parsed["all_steps"]:
+            # Strip keyword prefix
+            step_body = re.sub(r"^(?:Given|When|Then|And|But)\s+", "", step_text)
+            matched = False
+            for pat in all_patterns:
+                try:
+                    # Try Cucumber expression: replace {…} with .*
+                    regex_pat = re.sub(r"\{[^}]+\}", ".*", pat)
+                    if re.fullmatch(regex_pat, step_body, re.IGNORECASE):
+                        matched = True
+                        break
+                except re.error:
+                    pass
+            if not matched:
+                unmatched.append(step_body)
+        if unmatched:
+            for step in unmatched:
+                warnings.append(
+                    f"Gherkin step has no matching step definition: \"{step}\""
+                )
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "suggestions": suggestions,
+        "step_patterns_found": len(all_patterns),
+    }
+
+
+def _extract_element_hints(gherkin: str) -> list:
+    text = gherkin.lower()
+    hints = []
+    if "photo" in text or "image" in text or "crop" in text:
+        hints += [
+            ("profilePhoto", "profile-photo", "user profile photo image"),
+            ("imageEditorModal", "image-editor-modal", "image crop editor modal"),
+            ("cropHandle", "crop-handle", "image crop handle"),
+            ("zoomSlider", "zoom-slider", "image zoom slider"),
+            ("initialsAvatar", "initials-avatar", "user initials avatar fallback"),
+        ]
+    if "modal" in text or "dialog" in text:
+        hints += [
+            ("modalContainer", "modal-container", "modal or dialog container"),
+            ("modalCloseBtn", "modal-close-btn", "modal close button"),
+        ]
+    if "filter" in text or "search" in text:
+        hints += [
+            ("searchInput", "search-input", "search or filter input"),
+            ("filterDropdown", "filter-dropdown", "filter dropdown"),
+        ]
+    return hints
+
+
+# ============================================================================
+# Helix-QA Integration: Append-Only File Handling & Deduplication
+# ============================================================================
+
+def _file_exists(file_path: str) -> bool:
+    """Check if file exists."""
+    return Path(file_path).exists()
+
+
+def _read_file(file_path: str) -> str:
+    """Read file content. Return empty string if file does not exist."""
+    if not _file_exists(file_path):
+        return ""
+    try:
+        return Path(file_path).read_text(encoding="utf-8")
+    except Exception:
+        return ""
+
+
+def _parse_locators_from_file(ts_content: str) -> dict:
+    """Extract existing locator keys and selectors from locators.ts file.
+    
+    Returns dict: {
+        "keys": ["pageContainer", "submitBtn", ...],
+        "locators": {
+            "pageContainer": {"selector": "...", "intent": "...", "stability": ...},
+            ...
+        }
+    }
+    """
+    keys = []
+    locators_dict = {}
+    
+    # Match pattern: keyName: { selector: "...", intent: '...', ... }
+    pattern = r'(\w+):\s*\{\s*selector:\s*"([^"]+)".*?intent:\s*[\'"]([^\'"]+)'
+    
+    for match in re.finditer(pattern, ts_content):
+        key_name, selector, intent = match.groups()
+        keys.append(key_name)
+        locators_dict[key_name] = {
+            "selector": selector,
+            "intent": intent,
+        }
+    
+    return {"keys": keys, "locators": locators_dict}
+
+
+def _parse_page_methods_from_file(ts_content: str) -> dict:
+    """Extract existing method names from page object .ts file.
+    
+    Returns dict: {
+        "methods": ["navigate", "submitForm", "fillPrimaryInput", ...],
+        "pattern": "async methodName(...): Promise<...>"
+    }
+    """
+    methods = []
+    
+    # Match pattern: async methodName(...): Promise<...> {
+    pattern = r'async\s+(\w+)\s*\('
+    
+    for match in re.finditer(pattern, ts_content):
+        method_name = match.group(1)
+        methods.append(method_name)
+    
+    return {"methods": methods}
+
+
+def _parse_steps_from_file(ts_content: str) -> dict:
+    """Extract existing step definition patterns from steps .ts file.
+    
+    Returns dict: {
+        "step_patterns": ["given step text", "when step text", ...],
+        "by_keyword": {"Given": [...], "When": [...], "Then": [...]}
+    }
+    """
+    step_patterns = []
+    by_keyword = {"Given": [], "When": [], "Then": []}
+    
+    # Match pattern: Given(/^step pattern$/,
+    pattern = r'(Given|When|Then)\s*\(\s*/\^([^$]+)\$/'
+    
+    for match in re.finditer(pattern, ts_content):
+        keyword, step_text = match.groups()
+        # Unescape regex pattern
+        step_text = step_text.replace(r'\ ', ' ').replace(r'\.', '.').replace(r'\+', '+')
+        step_patterns.append(step_text)
+        by_keyword.setdefault(keyword, []).append(step_text)
+    
+    return {"step_patterns": step_patterns, "by_keyword": by_keyword}
+
+
+def _parse_scenarios_from_feature_file(feature_content: str) -> dict:
+    """Extract existing scenario titles from feature file.
+    
+    Returns dict: {
+        "scenario_titles": ["Scenario 1 Title", "Scenario 2 Title", ...],
+        "scenario_count": N
+    }
+    """
+    scenario_titles = []
+    
+    # Match pattern: Scenario: Scenario Title
+    pattern = r'^\s*Scenario:\s+(.+)$'
+    
+    for line in feature_content.splitlines():
+        match = re.match(pattern, line)
+        if match:
+            scenario_titles.append(match.group(1).strip())
+    
+    return {"scenario_titles": scenario_titles, "scenario_count": len(scenario_titles)}
+
+
+def _parse_utils_locators_from_file(ts_content: str) -> dict:
+    """Extract existing utility locator keys and selectors from src/utils/locators/*.ts files.
+    
+    Returns dict: {
+        "keys": ["locator1", "locator2", ...],
+        "locators": {
+            "locator1": {"selector": "...", "intent": "..."},
+            ...
+        }
+    }
+    """
+    keys = []
+    locators_dict = {}
+    
+    # Match pattern: export const locatorName = { selector: "...", intent: '...' }
+    pattern = r"export\s+const\s+(\w+)\s*=\s*\{[^}]*selector:\s*['\"]([^'\"]+)['\"][^}]*intent:\s*['\"]([^'\"]+)['\"]"
+    
+    for match in re.finditer(pattern, ts_content, re.DOTALL):
+        key_name, selector, intent = match.groups()
+        keys.append(key_name)
+        locators_dict[key_name] = {
+            "selector": selector,
+            "intent": intent,
+        }
+    
+    return {"keys": keys, "locators": locators_dict}
+
+
+def _merge_utils_locators_ts(new_content: str, existing_content: str, file_name: str) -> str:
+    """Merge new utility locators into existing file, avoiding duplicates.
+    
+    Args:
+        new_content: New utility locator content
+        existing_content: Existing file content
+        file_name: Name of the utility locator file (for logging)
+    
+    Returns:
+        merged content with new locators appended
+    """
+    if not existing_content:
+        return new_content
+    
+    # Parse existing locators
+    parsed = _parse_utils_locators_from_file(existing_content)
+    existing_keys = parsed["keys"]
+    
+    # Parse new locators
+    new_parsed = _parse_utils_locators_from_file(new_content)
+    new_keys = new_parsed["keys"]
+    
+    # Filter out locators that already exist
+    unique_keys = [k for k in new_keys if k not in existing_keys]
+    
+    if not unique_keys:
+        return existing_content
+    
+    # Extract new unique locators from new_content and append
+    new_entries = []
+    for key_name in unique_keys:
+        pattern = rf"export\s+const\s+{key_name}\s*=\s*{{[^}}]*}}"
+        match = re.search(pattern, new_content, re.DOTALL)
+        if match:
+            new_entries.append(match.group(0))
+    
+    if new_entries:
+        merged = existing_content + "\n\n" + "\n\n".join(new_entries)
+        return merged
+    
+    return existing_content
+
+
+def _generate_unique_locator_key(key: str, existing_keys: list) -> str:
+    """Generate a unique locator key when a conflict occurs.
+    
+    Strategy: append _1, _2, etc. until a unique name is found.
+    
+    Example: If 'submitBtn' exists, generateunique 'submitBtn_1', 'submitBtn_2', etc.
+    Helix-QA Integration: On conflict, the new locator gets the unique name (existing one is never modified).
+    """
+    candidate = key
+    counter = 1
+    while candidate in existing_keys:
+        candidate = f"{key}_{counter}"
+        counter += 1
+    return candidate
+
+
+def _append_to_file(file_path: str, content: str) -> None:
+    """Append content to file, creating it if it does not exist."""
+    path = Path(file_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    
+    if path.exists():
+        # Append with a newline separator
+        existing = path.read_text(encoding="utf-8")
+        path.write_text(existing + "\n" + content, encoding="utf-8")
+    else:
+        # Create new file
+        path.write_text(content, encoding="utf-8")
+
+
+def _merge_locators_ts(new_locators_section: str, existing_content: str, page_class: str) -> str:
+    """Merge new locators into existing locators.ts, avoiding duplicates.
+    
+    Args:
+        new_locators_section: The full new locators section (everything between export const ... and closing brace)
+        existing_content: The existing file content
+        page_class: The page class name (e.g., "HomePage")
+    
+    Returns:
+        merged content with new locators appended to the export object
+    """
+    if not existing_content:
+        return new_locators_section
+    
+    # Parse existing locator keys
+    parsed = _parse_locators_from_file(existing_content)
+    existing_keys = parsed["keys"]
+    
+    # Extract locators from new section using regex
+    new_pattern = r'(\w+):\s*\{\s*selector:\s*"([^"]+)".*?intent:\s*[\'"]([^\'"]+)[\'"].*?\}'
+    new_locators_dict = {}
+    
+    for match in re.finditer(new_pattern, new_locators_section):
+        key_name, selector, intent = match.groups()
+        new_locators_dict[key_name] = {"selector": selector, "intent": intent}
+    
+    # Filter out existing keys
+    unique_locators = {}
+    locator_conflicts = {}
+    
+    for key_name, entries in new_locators_dict.items():
+        if key_name not in existing_keys:
+            unique_locators[key_name] = entries
+        else:
+            # Check if selector is the same
+            if parsed["locators"].get(key_name, {}).get("selector") != entries["selector"]:
+                # Conflict: same key, different selector
+                new_key = _generate_unique_locator_key(key_name, existing_keys + list(unique_locators.keys()))
+                locator_conflicts[new_key] = entries
+    
+    # If all locators already exist, return existing content
+    if not unique_locators and not locator_conflicts:
+        return existing_content
+    
+    # Append new unique locators to the existing content
+    # Find the closing brace of the locators object
+    match = re.search(r'}} as const;\s*$', existing_content, re.MULTILINE)
+    if not match:
+        return existing_content
+    
+    insert_pos = match.start()
+    
+    new_entries = []
+    for key_name, entry in {**unique_locators, **locator_conflicts}.items():
+        selector = entry["selector"]
+        intent = entry["intent"]
+        new_entries.append(f'  {key_name}: {{ selector: "{selector}", intent: \'{intent}\', stability: 0 }},')
+    
+    if new_entries:
+        merged = (
+            existing_content[:insert_pos] +
+            "\n" + "\n".join(new_entries) +
+            "\n" +
+            existing_content[insert_pos:]
+        )
+        return merged
+    
+    return existing_content
+
+
+def _merge_page_object_ts(new_methods_section: str, existing_content: str, page_class: str, kebab: str) -> str:
+    """Merge new methods into existing page object .ts file, avoiding duplicates."""
+    if not existing_content:
+        return new_methods_section
+    
+    parsed = _parse_page_methods_from_file(existing_content)
+    existing_methods = parsed["methods"]
+    
+    # Extract method names from new section
+    new_pattern = r'async\s+(\w+)\s*\('
+    new_methods = []
+    for match in re.finditer(new_pattern, new_methods_section):
+        new_methods.append(match.group(1))
+    
+    # Find methods to add (not in existing)
+    unique_methods = [m for m in new_methods if m not in existing_methods]
+    
+    if not unique_methods:
+        return existing_content
+    
+    # Extract only the unique methods from the new section
+    methods_to_add = []
+    for method_name in unique_methods:
+        # Find the method in the new section
+        pattern = rf'async\s+{method_name}\s*\(.*?\n  \}}\n'
+        match = re.search(pattern, new_methods_section, re.DOTALL)
+        if match:
+            methods_to_add.append(match.group(0))
+    
+    if methods_to_add:
+        # Append to the existing content before the closing brace of the class
+        merged = re.sub(
+            r'(\n\})\s*$',
+            '\n\n' + '\n\n'.join(methods_to_add) + r'\1',
+            existing_content,
+            flags=re.MULTILINE
+        )
+        return merged
+    
+    return existing_content
+
+
+def _merge_steps_ts(new_steps_section: str, existing_content: str, page_class: str, kebab: str) -> str:
+    """Merge new steps into existing steps .ts file, avoiding duplicates."""
+    if not existing_content:
+        return new_steps_section
+    
+    parsed = _parse_steps_from_file(existing_content)
+    existing_patterns = parsed["step_patterns"]
+    
+    # Extract new step patterns
+    new_pattern_list = []
+    for line in new_steps_section.splitlines():
+        match = re.search(r'/\^([^$]+)\$/', line)
+        if match:
+            step_text = match.group(1)
+            new_pattern_list.append(step_text)
+    
+    # Filter out duplicates
+    unique_steps = []
+    for step_line in new_steps_section.splitlines():
+        # Check if this is a Given/When/Then block
+        if re.match(r'(Given|When|Then)\s*\(', step_line):
+            # Find the step pattern
+            match = re.search(r'/\^([^$]+)\$/', step_line)
+            if match:
+                step_text = match.group(1)
+                if step_text not in existing_patterns:
+                    unique_steps.append(step_line)
+    
+    if not unique_steps:
+        return existing_content
+    
+    # Append before the last ";" if it exists, or before the "export default" or end of file
+    merged = re.sub(
+        r'(\);)\s*$',
+        r'\1\n\n' + '\n\n'.join(unique_steps),
+        existing_content,
+        flags=re.MULTILINE
+    )
+    return merged
+
+
+def _merge_feature_file(new_feature_content: str, existing_content: str) -> str:
+    """Merge scenarios into existing feature file, avoiding duplicate scenario titles."""
+    if not existing_content:
+        return new_feature_content
+    
+    parsed = _parse_scenarios_from_feature_file(existing_content)
+    existing_titles = parsed["scenario_titles"]
+    
+    # Extract new scenarios
+    scenario_blocks = []
+    current_scenario = []
+    in_scenario = False
+    
+    for line in new_feature_content.splitlines():
+        if re.match(r'^\s*Scenario:', line):
+            if current_scenario:
+                scenario_blocks.append('\n'.join(current_scenario))
+            current_scenario = [line]
+            in_scenario = True
+        elif in_scenario:
+            if line.strip() and not re.match(r'^\s*#', line):
+                current_scenario.append(line)
+            elif not line.strip():
+                current_scenario.append(line)
+    
+    if current_scenario:
+        scenario_blocks.append('\n'.join(current_scenario))
+    
+    # Filter out scenarios with existing titles
+    unique_scenarios = []
+    for scenario_block in scenario_blocks:
+        match = re.search(r'Scenario:\s+(.+)$', scenario_block, re.MULTILINE)
+        if match:
+            title = match.group(1).strip()
+            if title not in existing_titles:
+                unique_scenarios.append(scenario_block)
+    
+    if not unique_scenarios:
+        return existing_content
+    
+    # Append scenarios to the feature file
+    merged = existing_content + "\n\n" + "\n\n".join(unique_scenarios)
+    return merged
+
+
+# ============================================================================
+# generate_playwright_code
+# ============================================================================
+
+def _generate_playwright_code(
+    gherkin, page_class, app_name, healing_strategy,
+    auth_hook, enable_visual_regression, enable_timing_healing,
+    context_map=None, helix_project_root=None,
+):
+    kebab     = _to_kebab(page_class)
+    camel     = page_class[0].lower() + page_class[1:]
+    all_steps = _parse_gherkin_steps(gherkin)["all_steps"]
+    feature_title = page_class
+    for line in gherkin.splitlines():
+        if line.strip().startswith("Feature:"):
+            feature_title = line.strip()[8:].strip()
+            break
+
+    locator_source = "playwright-mcp-verified" if context_map else "gherkin-inferred"
+
+    # Generate new content
+    new_locators = _gen_locators(page_class, kebab, gherkin, context_map)
+    new_page_object = _gen_page_object(
+        page_class, kebab, camel, gherkin, healing_strategy,
+        enable_visual_regression, enable_timing_healing)
+    new_step_defs = _gen_step_defs(
+        page_class, kebab, camel, all_steps, auth_hook)
+    new_feature = _gen_feature_file(gherkin, kebab, page_class)
+
+    # Normalize feature file: auto-quote unquoted string parameters so they
+    # match the generated step-definition regex patterns.
+    new_feature, normalization_warnings = _normalize_feature_steps(new_feature, new_step_defs)
+
+    # Handle Helix-QA project integration: read existing files and merge
+    if helix_project_root:
+        helix_root = Path(helix_project_root)
+        
+        # Locators merge
+        locators_path = str(helix_root / "src" / "locators" / f"{kebab}.locators.ts")
+        existing_locators = _read_file(locators_path)
+        new_locators = _merge_locators_ts(new_locators, existing_locators, page_class)
+        
+        # Page object merge
+        page_path = str(helix_root / "src" / "pages" / f"{kebab}.page.ts")
+        existing_page = _read_file(page_path)
+        new_page_object = _merge_page_object_ts(new_page_object, existing_page, page_class, kebab)
+        
+        # Steps merge
+        steps_path = str(helix_root / "src" / "test" / "steps" / f"{kebab}.steps.ts")
+        existing_steps = _read_file(steps_path)
+        new_step_defs = _merge_steps_ts(new_step_defs, existing_steps, page_class, kebab)
+        
+        # Feature file merge
+        feature_path = str(helix_root / "src" / "test" / "features" / f"{kebab}.feature")
+        existing_feature = _read_file(feature_path)
+        new_feature = _merge_feature_file(new_feature, existing_feature)
+
+    files = {
+        f"src/locators/{kebab}.locators.ts":      new_locators,
+        f"src/pages/{kebab}.page.ts":             new_page_object,
+        f"src/test/steps/{kebab}.steps.ts":       new_step_defs,
+        f"src/test/features/{kebab}.feature":     new_feature,
+        "config/cucumber.js (add this profile)":  _gen_cucumber_profile(kebab, app_name, auth_hook),
+    }
+
+    layers = ["LocatorHealer (selector → role → label → text → AI Vision)"]
+    if enable_timing_healing:
+        layers.append("TimingHealer (network trace drift → auto-adjusted timeouts → HealingDashboard)")
+    if enable_visual_regression:
+        layers.append("VisualIntentChecker (element screenshot diff against baseline → HealingDashboard)")
+
+    hint = (
+        "context_map was provided — locators.ts uses accessibility-tree-verified selectors."
+        if context_map else
+        "No context_map provided — locators.ts uses Gherkin inference (stability=0). "
+        "Run Playwright MCP (npx @playwright/mcp@latest --port 8931) and use "
+        "browser_navigate + browser_snapshot to build a verified context_map."
+    )
+
+    merge_note = (
+        f"\n✓ Helix-QA Integration: Files prepared for {helix_project_root}\n"
+        "  • Locators merged (no duplicates, conflicts renamed)\n"
+        "  • Page objects merged (new methods appended)\n"
+        "  • Step definitions merged (new steps appended)\n"
+        "  • Feature file merged (new scenarios appended)\n"
+        "  Ready to write to disk using write-helix-files or agent 4."
+    ) if helix_project_root else ""
+
+    # Run pre-output validation across all three checks
+    validation = _run_pre_output_validation(
+        files,
+        f"src/test/features/{kebab}.feature",
+        f"src/test/steps/{kebab}.steps.ts",
+        kebab,
+        page_class,
+    )
+    if normalization_warnings:
+        validation["warnings"] = normalization_warnings + validation.get("warnings", [])
+        validation["normalization_warnings"] = normalization_warnings
+
+    return {
+        "files": files, "file_count": len(files),
+        "page_class": page_class, "feature_title": feature_title,
+        "step_count": len(all_steps), "healing_strategy": healing_strategy,
+        "healing_layers": layers,
+        "locator_source": locator_source,
+        "validation": validation,
+        "note": hint + merge_note,
+        "scaffold_note": "Run scaffold_locator_repository once per project to generate all 6 infrastructure files.",
+    }
+
+
+def _gen_locators(page_class, kebab, gherkin, context_map=None):
+    if context_map and context_map.get("locators"):
+        # context_map from Playwright MCP snapshot: list of { key, selector, intent, stability, visualIntent? }
+        cdp_entries = _gen_locators_from_context_map(context_map)
+    elif context_map and isinstance(context_map, dict) and any(
+        isinstance(v, dict) and "selector" in v for v in context_map.values()
+    ):
+        # context_map as flat dict: { key: { selector, intent, stability, visualIntent? } }
+        cdp_entries = _gen_locators_from_flat_map(context_map)
+    else:
+        cdp_entries = None
+
+    if cdp_entries is None:
+        extras = ""
+        for k, t, i in _extract_element_hints(gherkin):
+            extras += f"  {k}: {{ selector: \"[data-testid='{t}']\", intent: '{i}', visualIntent: true }},\n"
+        source_note = (
+            " *\n"
+            " * ⚠ GHERKIN-INFERRED: These selectors are placeholder data-testid values.\n"
+            " * Run Playwright MCP (npx @playwright/mcp@latest --port 8931) and use\n"
+            " * browser_navigate + browser_snapshot to replace them with real selectors."
+        )
+    else:
+        extras = cdp_entries
+        source_note = (
+            " *\n"
+            " * SOURCE: Playwright MCP accessibility tree snapshot.\n"
+            " * Stability rank: data-testid(100) > aria-role+name(90) > id(80) > aria-label(70) > placeholder(60).\n"
+            " * All selectors derived from real AX nodes — zero hallucinated values."
+        )
+
+    return f'''/**
+ * Locators: {page_class}Page
+ * Pattern: {{ selector, intent, stability?, visualIntent? }}
+ *   selector:     CSS selector derived from accessibility tree (or Gherkin inference)
+ *   intent:       used by LocatorHealer (AI Vision fallback) and VisualIntentChecker
+ *   stability:    0–100 confidence score (100 = data-testid, 0 = gherkin-inferred)
+ *   visualIntent: when true, VisualIntentChecker screenshots this element at assertions{source_note}
+ */
+export const {page_class}Locators = {{
+  pageContainer:     {{ selector: "[data-testid='{kebab}-container']",    intent: '{page_class} main page container',    stability: 0 }},
+  primaryActionBtn:  {{ selector: "[data-testid='{kebab}-action-btn']",   intent: 'primary action button',               stability: 0, visualIntent: true }},
+  submitBtn:         {{ selector: "[data-testid='{kebab}-submit']",        intent: 'submit form button',                  stability: 0, visualIntent: true }},
+  confirmBtn:        {{ selector: "[data-testid='{kebab}-confirm']",       intent: 'confirm action button',               stability: 0, visualIntent: true }},
+  cancelBtn:         {{ selector: "[data-testid='{kebab}-cancel']",        intent: 'cancel or close button',              stability: 0 }},
+  saveBtn:           {{ selector: "[data-testid='{kebab}-save']",          intent: 'save changes button',                 stability: 0, visualIntent: true }},
+  primaryInputField: {{ selector: "[data-testid='{kebab}-primary-input']", intent: 'primary text input',                  stability: 0 }},
+  fileInput:         {{ selector: "input[type='file']",                    intent: 'file upload input',                   stability: 70 }},
+  successToast:      {{ selector: "[data-testid='toast-success']",         intent: 'success notification toast',          stability: 0, visualIntent: true }},
+  errorToast:        {{ selector: "[data-testid='toast-error']",           intent: 'error notification toast',            stability: 0, visualIntent: true }},
+  validationError:   {{ selector: "[data-testid='validation-error']",      intent: 'form validation error message',       stability: 0, visualIntent: true }},
+  successIndicator:  {{ selector: "[data-testid='{kebab}-success']",       intent: 'success state indicator',             stability: 0, visualIntent: true }},
+  updatedIndicator:  {{ selector: "[data-testid='{kebab}-updated']",       intent: 'updated state indicator',             stability: 0 }},
+{extras}}} as const;
+export type LocatorKey = keyof typeof {page_class}Locators;
+'''
+
+
+def _gen_locators_from_context_map(context_map: dict) -> str:
+    """Convert context_map with a 'locators' list (from Playwright MCP snapshot parsing)."""
+    lines = []
+    for loc in context_map.get("locators", []):
+        key       = loc["key"]
+        selector  = loc["selector"]
+        intent    = loc["intent"]
+        stability = loc.get("stability", 0)
+        vi        = ", visualIntent: true" if loc.get("visualIntent") else ""
+        lines.append(
+            f"  // stability={stability}\n"
+            f"  {key}: {{ selector: \"{selector}\", intent: '{intent}', stability: {stability}{vi} }},"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _gen_locators_from_flat_map(context_map: dict) -> str:
+    """Convert context_map as flat dict { key: { selector, intent, stability, visualIntent? } }."""
+    lines = []
+    for key, entry in context_map.items():
+        if not isinstance(entry, dict) or "selector" not in entry:
+            continue
+        selector  = entry["selector"]
+        intent    = entry.get("intent", key)
+        stability = entry.get("stability", 0)
+        vi        = ", visualIntent: true" if entry.get("visualIntent") else ""
+        lines.append(
+            f"  // stability={stability}\n"
+            f"  {key}: {{ selector: \"{selector}\", intent: '{intent}', stability: {stability}{vi} }},"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _gen_page_object(page_class, kebab, camel, gherkin, healing_strategy,
+                      enable_visual_regression, enable_timing_healing):
+    steps     = _parse_gherkin_steps(gherkin)["all_steps"]
+    stubs     = _build_method_stubs(camel, steps)
+    vi_import = 'import { VisualIntentChecker } from "@utils/locators/VisualIntentChecker";' if enable_visual_regression else ""
+    th_import = 'import { TimingHealer } from "@utils/locators/TimingHealer";' if enable_timing_healing else ""
+    vi_field  = "private readonly visual: VisualIntentChecker;" if enable_visual_regression else ""
+    th_field  = "private readonly timing: TimingHealer;" if enable_timing_healing else ""
+    vi_init   = "this.visual = new VisualIntentChecker(this.page, fixture().logger, this.repo);" if enable_visual_regression else ""
+    th_init   = "this.timing = new TimingHealer(this.page, fixture().logger, this.repo);" if enable_timing_healing else ""
+    tn        = '    await this.timing.waitForNetworkIdle("navigate");' if enable_timing_healing else ""
+    ts_       = '    await this.timing.waitForNetworkIdle("submitForm");' if enable_timing_healing else ""
+    vc        = '    await this.visual.check("successToast", this.loc.successToast.selector, this.loc.successToast.intent);' if enable_visual_regression else ""
+
+    return f'''import {{ Page, expect }} from "@playwright/test";
+import {{ fixture }} from "@hooks/pageFixture";
+import {{ {page_class}Locators }} from "./locators";
+import {{ LocatorHealer }} from "@utils/locators/LocatorHealer";
+import {{ LocatorRepository }} from "@utils/locators/LocatorRepository";
+{vi_import}
+{th_import}
+import {{ EnvironmentManager }} from "@helper/environment/environmentManager.util";
+
+/**
+ * {page_class}Page — Three-Layer Self-Healing Page Object
+ *
+ * Layer 1 — Locator Healing ({healing_strategy}):
+ *   primary selector → role-based → label-based → text-based → playwright-cli + Claude AI Vision
+ *   → DevToolsHealer AX tree (CDPSession) → DevToolsHealer bounding box (CDPSession)
+ *   Healed selectors persisted in LocatorRepository — zero overhead on repeat runs.
+ *
+{" * Layer 2 — Timing Healing (TimingHealer): intercepts network traces, auto-heals timeout drift." if enable_timing_healing else ""}
+{" *" if enable_timing_healing else ""}
+{" * Layer 3 — Visual Intent (VisualIntentChecker): element screenshot diff at assertions." if enable_visual_regression else ""}
+{" *" if enable_visual_regression else ""}
+{" * HealingDashboard: http://localhost:7890 — approve/reject all AI suggestions." if (enable_timing_healing or enable_visual_regression) else ""}
+ *
+ * RULE: Never call page.click / page.fill / page.locator directly.
+ */
+export default class {page_class}Page {{
+  private readonly page:   Page;
+  private readonly healer: LocatorHealer;
+  private readonly repo:   LocatorRepository;
+  private readonly loc  = {page_class}Locators;
+  private readonly env:    EnvironmentManager;
+  {vi_field}
+  {th_field}
+
+  constructor(page?: Page) {{
+    this.page   = page ?? fixture().page;
+    this.env    = new EnvironmentManager();
+    this.repo   = fixture().locatorRepository ?? new LocatorRepository();
+    this.healer = new LocatorHealer(this.page, fixture().logger, this.repo);
+    {vi_init}
+    {th_init}
+    Object.entries(this.loc).forEach(([key, val]) =>
+      this.repo.register(key, val.selector, val.intent));
+  }}
+
+  async navigate(): Promise<void> {{
+    const url = `${{this.env.getBaseUrl()}}/${{this.env.getPath("{kebab}")}}`;
+    fixture().logger.info(`Navigating to ${{url}}`);
+    await this.page.goto(url, {{ waitUntil: "networkidle" }});
+{tn}
+    await this.healer.assertVisibleWithHealing(
+      "pageContainer", this.loc.pageContainer.selector, this.loc.pageContainer.intent);
+  }}
+
+  async waitForPageLoad(): Promise<void> {{
+    await this.healer.assertVisibleWithHealing(
+      "pageContainer", this.loc.pageContainer.selector, this.loc.pageContainer.intent);
+  }}
+
+  async submitForm(): Promise<void> {{
+    await this.healer.clickWithHealing(
+      "submitBtn", this.loc.submitBtn.selector, this.loc.submitBtn.intent);
+{ts_}
+  }}
+
+  async confirmAction(): Promise<void> {{
+    await this.healer.clickWithHealing(
+      "confirmBtn", this.loc.confirmBtn.selector, this.loc.confirmBtn.intent);
+  }}
+
+  async clickCancel(): Promise<void> {{
+    await this.healer.clickWithHealing(
+      "cancelBtn", this.loc.cancelBtn.selector, this.loc.cancelBtn.intent);
+  }}
+
+  async clickSave(): Promise<void> {{
+    await this.healer.clickWithHealing(
+      "saveBtn", this.loc.saveBtn.selector, this.loc.saveBtn.intent);
+  }}
+
+  async fillPrimaryInput(value: string): Promise<void> {{
+    await this.healer.fillWithHealing(
+      "primaryInputField", this.loc.primaryInputField.selector, value, this.loc.primaryInputField.intent);
+  }}
+
+  async uploadFile(buffer: Buffer, fileName: string, mimeType: string): Promise<void> {{
+    await this.page.locator(this.loc.fileInput.selector).setInputFiles({{ name: fileName, mimeType, buffer }});
+  }}
+
+  async verifySuccessToast(): Promise<void> {{
+    await this.healer.assertVisibleWithHealing(
+      "successToast", this.loc.successToast.selector, this.loc.successToast.intent);
+{vc}
+    fixture().logger.info("✓ Success toast verified (locator + visual)");
+  }}
+
+  async verifyErrorToast(): Promise<void> {{
+    await this.healer.assertVisibleWithHealing(
+      "errorToast", this.loc.errorToast.selector, this.loc.errorToast.intent);
+    fixture().logger.info("✓ Error toast verified");
+  }}
+
+  async verifyValidationErrors(): Promise<void> {{
+    await this.healer.assertVisibleWithHealing(
+      "validationError", this.loc.validationError.selector, this.loc.validationError.intent);
+    const count = await this.page.locator(this.loc.validationError.selector).count();
+    expect(count).toBeGreaterThan(0);
+  }}
+
+  async verifySuccessState(): Promise<void> {{
+    await this.healer.assertVisibleWithHealing(
+      "successIndicator", this.loc.successIndicator.selector, this.loc.successIndicator.intent);
+  }}
+
+  async verifyStatePersisted(): Promise<void> {{
+    await this.healer.assertVisibleWithHealing(
+      "updatedIndicator", this.loc.updatedIndicator.selector, this.loc.updatedIndicator.intent);
+  }}
+
+  async reloadAndVerify(): Promise<void> {{
+    await this.page.reload({{ waitUntil: "networkidle" }});
+    await this.verifyStatePersisted();
+  }}
+
+{stubs}
+}}
+'''
+
+
+def _build_method_stubs(camel, steps):
+    stubs, seen = [], set()
+    for step in steps:
+        lower = step.lower()
+        if "refresh" in lower and "refresh" not in seen:
+            seen.add("refresh")
+            stubs.append('''  async refreshPage(): Promise<void> {
+    await this.page.reload({ waitUntil: "networkidle" });
+    await this.waitForPageLoad();
+  }''')
+        if "initials" in lower and "initials" not in seen:
+            seen.add("initials")
+            stubs.append('''  async verifyInitialsAvatar(): Promise<void> {
+    const sel = (this.loc as any).initialsAvatar?.selector ?? "[data-testid='initials-avatar']";
+    const el  = this.page.locator(sel);
+    await expect(el).toBeVisible({ timeout: 10_000 });
+    const text = await el.textContent() ?? "";
+    expect(text.trim()).toMatch(/^[A-Z]{1,2}$/);
+    fixture().logger.info(`✓ Initials: "${text.trim()}"`);
+  }''')
+        if "persist" in lower and "persist" not in seen:
+            seen.add("persist")
+            stubs.append('''  async verifyDataPersistenceAfterRefresh(): Promise<void> {
+    await this.page.reload({ waitUntil: "networkidle" });
+    await this.verifyStatePersisted();
+    fixture().logger.info("✓ State persisted after refresh");
+  }''')
+    return "\n\n".join(stubs)
+
+
+def _gen_step_defs(page_class, kebab, camel, all_steps, auth_hook):
+    bg = ""
+    if auth_hook == "microsoft-sso":
+        bg = f'''
+Given(
+  /^user logs in with Microsoft SSO as "(.+)"$/,
+  async function (userType: string): Promise<void> {{
+    fixture().logger.info(`SSO login as ${{userType}}`);
+  }},
+);
+Given(
+  /^user of type "(.+)" is ready to login$/,
+  async function (userType: string): Promise<void> {{
+    fixture().logger.info(`Preparing login for ${{userType}}`);
+  }},
+);
+'''
+    mappings = [
+        (["navigates to", "is on the"],             f"{camel}Page.navigate()"),
+        (["submits the form", "clicks submit"],       f"{camel}Page.submitForm()"),
+        (["confirms the action"],                     f"{camel}Page.confirmAction()"),
+        (["clicks cancel", "clicks close"],           f"{camel}Page.clickCancel()"),
+        (["clicks save"],                             f"{camel}Page.clickSave()"),
+        (["refreshes the page"],                      f"{camel}Page.refreshPage()"),
+        (["selects a valid file", "uploads a valid"], f"{camel}Page.uploadFile(Buffer.alloc(5*1024*1024),'test.jpg','image/jpeg')"),
+        (["exceeds the maximum", "oversized"],        f"{camel}Page.uploadFile(Buffer.alloc(5*1024*1024+1),'over.jpg','image/jpeg')"),
+        (["success toast", "success notification"],   f"{camel}Page.verifySuccessToast()"),
+        (["error toast", "error notification"],       f"{camel}Page.verifyErrorToast()"),
+        (["validation error"],                        f"{camel}Page.verifyValidationErrors()"),
+        (["operation completes", "updated state"],    f"{camel}Page.verifySuccessState()"),
+        (["still be visible", "persists"],            f"{camel}Page.verifyStatePersisted()"),
+        (["initials", "fallback avatar"],             f"{camel}Page.verifyInitialsAvatar()"),
+    ]
+    lines, seen = [], set()
+    for step in all_steps:
+        m = re.match(r"^(Given|When|Then|And|But)\s+", step)
+        if not m: continue
+        kw, text = m.group(1), step[len(m.group(0)):]
+        norm = re.sub(r"\s+", " ", text.lower())
+        if norm in seen: continue
+        seen.add(norm)
+        lower = step.lower()
+        method = next((mth for kws, mth in mappings if any(k in lower for k in kws)), None)
+        if not method: continue
+        pat = re.sub(r'"[^"]+"', '(.+)', re.escape(text)).replace(r"\ ", " ")
+        lines.append(f'''{kw}(
+  /^{pat}$/,
+  async function (): Promise<void> {{
+    await {method};
+  }},
+);
+''')
+    return f'''import {{ Given, When, Then }} from "@cucumber/cucumber";
+import {{ expect }} from "@playwright/test";
+import {{ fixture }} from "@hooks/pageFixture";
+import {page_class}Page from "@pages/{kebab}/{kebab}.page";
+
+/**
+ * Step Definitions: {page_class}
+ * HealingDashboard: http://localhost:7890 — review pending suggestions.
+ */
+let {camel}Page: {page_class}Page;
+{bg}
+{"".join(lines)}
+'''
+
+
+def _gen_feature_file(gherkin: str, kebab: str, page_class: str) -> str:
+    """Generate feature file content. Returns the full feature file as-is from gherkin."""
+    # The feature file is already in gherkin format, so we just return it
+    # (This allows consume the gherkin directly without modification)
+    return gherkin
+
+
+def _gen_cucumber_profile(kebab, app_name, auth_hook):
+    profile = kebab.replace("-", "_")
+    sso = '"src/test/steps/microsoftSSO.steps.ts",' if auth_hook == "microsoft-sso" else ""
+    return f'''// Add to config/cucumber.js
+{profile}: {{
+  tags: process.env.tags || "@{profile}",
+  paths: ["src/test/features/{kebab}.feature"],
+  require: ["src/test/steps/{kebab}.steps.ts", {sso} "src/hooks/hooks.ts"],
+  requireModule: ["ts-node/register", "tsconfig-paths/register"],
+  format: ["progress", "html:test-results/cucumber-report-{kebab}.html",
+           "json:test-results/cucumber-report-{kebab}.json", "rerun:@rerun.txt"],
+  parallel: 2, retry: 2, retryTagFilter: "@flaky",
+}},
+// Run: ENABLE_SELF_HEALING=true HEALING_DASHBOARD_PORT=7890 \\
+//   cucumber-js --config=config/cucumber.js -p {profile}
+'''
+
+
+# ============================================================================
+# Post-generation validation
+# ============================================================================
+
+_STEP_STOP_WORDS = frozenset([
+    'a', 'an', 'the', 'is', 'are', 'has', 'have', 'to', 'be', 'with',
+    'in', 'on', 'at', 'for', 'of', 'by', 'as', 'it', 'its', 'from',
+    'and', 'or', 'not', 'no', 'true', 'false', 'user', 'page',
+])
+
+
+def _normalize_feature_steps(feature_content: str, step_defs_content: str) -> tuple:
+    """Auto-quote unquoted string parameters in feature file steps.
+
+    Builds compiled regex patterns from the generated step definitions, then for
+    each feature step that does NOT already match any pattern, iteratively wraps
+    unquoted alphanumeric tokens in double-quotes until a match is found.
+
+    Returns (normalized_content: str, warnings: list[str]).
+    """
+    warnings: list = []
+
+    # Compile step-definition regex patterns
+    patterns: list = []
+    for line in step_defs_content.splitlines():
+        m = re.search(r'/\^(.+?)\$/', line)
+        if m:
+            pat_str = m.group(1).replace(r'\ ', r'\s+')
+            try:
+                patterns.append(re.compile(r'^' + pat_str + r'$', re.IGNORECASE))
+            except re.error:
+                pass
+
+    if not patterns:
+        return feature_content, warnings
+
+    kws = ('Given', 'When', 'Then', 'And', 'But')
+    result_lines: list = []
+
+    for line in feature_content.splitlines():
+        stripped = line.strip()
+        kw = next((k for k in kws if stripped.startswith(k + ' ')), None)
+        if not kw:
+            result_lines.append(line)
+            continue
+
+        indent = line[: len(line) - len(line.lstrip())]
+        text = stripped[len(kw) + 1:]
+
+        # Already matches a pattern — keep as-is
+        if any(p.match(text) for p in patterns):
+            result_lines.append(line)
+            continue
+
+        # Iteratively quote the first unquoted token that produces a match
+        fixed = text
+        for _ in range(5):  # at most 5 params per step
+            replaced = False
+            for tm in re.finditer(r'(?<!["\'\w])([A-Za-z][A-Za-z0-9_\-]+)(?!["\'\w])', fixed):
+                tok = tm.group(1)
+                if tok.lower() in _STEP_STOP_WORDS:
+                    continue
+                candidate = fixed[: tm.start(1)] + f'"{tok}"' + fixed[tm.end(1):]
+                if any(p.match(candidate) for p in patterns):
+                    warnings.append(
+                        f"Auto-quoted '{tok}' in step: \"{kw} {text}\" → \"{kw} {candidate}\""
+                    )
+                    fixed = candidate
+                    replaced = True
+                    break
+            if not replaced:
+                break
+
+        result_lines.append(f"{indent}{kw} {fixed}")
+
+    return '\n'.join(result_lines), warnings
+
+
+def _check_import_consistency(files: dict, kebab: str, page_class: str) -> list:
+    """Verify internal imports between generated .ts files resolve to known file keys.
+
+    Maps Helix-QA tsconfig path aliases and relative paths to expected keys in the
+    files dict. Reports any import whose resolved target is absent.
+
+    Returns list of issue strings.
+    """
+    issues: list = []
+
+    alias_map: dict = {
+        f"@pages/{kebab}/{kebab}.page": f"src/pages/{kebab}.page.ts",
+        f"@pages/{kebab}.page":         f"src/pages/{kebab}.page.ts",
+        "./locators":                    f"src/locators/{kebab}.locators.ts",
+        f"../locators/{kebab}.locators": f"src/locators/{kebab}.locators.ts",
+        f"@locators/{kebab}.locators":   f"src/locators/{kebab}.locators.ts",
+    }
+    internal_prefixes = ('./', '../', '@pages/', '@locators/')
+
+    for file_key, content in files.items():
+        if not file_key.endswith('.ts'):
+            continue
+        for m in re.finditer(r"""from\s+['"]([^'"]+)['"]""", content):
+            path = m.group(1)
+            if not any(path.startswith(p) for p in internal_prefixes):
+                continue
+            if not path.strip():
+                issues.append(f"{file_key}: empty import path detected")
+                continue
+            if path in alias_map:
+                target = alias_map[path]
+                if target not in files:
+                    issues.append(
+                        f"{file_key}: import '{path}' → expected '{target}' not in generated files"
+                    )
+
+    return issues
+
+
+def _validate_ts_syntax(content: str, file_name: str) -> list:
+    """Basic TypeScript syntax sanity checks.
+
+    Strips string literals, template literals, and comments before counting
+    brace/paren balance to avoid false positives from characters inside strings.
+
+    Returns list of error strings.
+    """
+    errors: list = []
+
+    # Strip literals and comments before balance checks
+    s = re.sub(r'`[^`]*`', '``', content)
+    s = re.sub(r'"[^"\n]*"', '""', s)
+    s = re.sub(r"'[^'\n]*'", "''", s)
+    s = re.sub(r'//[^\n]*', '', s)
+    s = re.sub(r'/\*.*?\*/', '', s, flags=re.DOTALL)
+
+    nb = s.count('{') - s.count('}')
+    if nb != 0:
+        errors.append(f"{file_name}: unbalanced braces (delta={nb:+d})")
+
+    np_ = s.count('(') - s.count(')')
+    if np_ != 0:
+        errors.append(f"{file_name}: unbalanced parentheses (delta={np_:+d})")
+
+    if re.search(r"""from\s+['"]{2}""", content):
+        errors.append(f"{file_name}: empty import path (from \"\")")
+
+    if ';;' in content:
+        errors.append(f"{file_name}: double semicolons found")
+
+    return errors
+
+
+def _validate_step_coverage(feature_content: str, step_defs_content: str) -> list:
+    """Return feature steps that have no matching step definition regex pattern.
+
+    Returns list of uncovered step strings (keyword included).
+    """
+    patterns: list = []
+    for line in step_defs_content.splitlines():
+        m = re.search(r'/\^(.+?)\$/', line)
+        if m:
+            pat_str = m.group(1).replace(r'\ ', r'\s+')
+            try:
+                patterns.append(re.compile(r'^' + pat_str + r'$', re.IGNORECASE))
+            except re.error:
+                pass
+
+    if not patterns:
+        return []
+
+    kws = ('Given', 'When', 'Then', 'And', 'But')
+    uncovered: list = []
+    seen: set = set()
+
+    for line in feature_content.splitlines():
+        stripped = line.strip()
+        kw = next((k for k in kws if stripped.startswith(k + ' ')), None)
+        if not kw:
+            continue
+        text = stripped[len(kw) + 1:]
+        key = text.strip().lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        if not any(p.match(text) for p in patterns):
+            uncovered.append(f"{kw} {text}")
+
+    return uncovered
+
+
+def _run_pre_output_validation(
+    files: dict, feature_key: str, step_key: str,
+    kebab: str, page_class: str,
+) -> dict:
+    """Run all post-generation validations and return a consolidated summary.
+
+    Checks:
+      1. Import consistency — internal @pages / ./ imports resolve to files dict keys.
+      2. TypeScript syntax  — brace/paren balance, empty imports, double semicolons.
+      3. Step coverage      — every unique feature step has a matching step definition.
+
+    Returns dict with keys: valid, errors, warnings, import_issues,
+                            syntax_issues, uncovered_steps.
+    """
+    all_errors: list = []
+    all_warnings: list = []
+
+    # 1 — Import consistency
+    import_issues = _check_import_consistency(files, kebab, page_class)
+    all_errors.extend(import_issues)
+
+    # 2 — TypeScript syntax per file
+    syntax_issues: dict = {}
+    for fk, fc in files.items():
+        if fk.endswith('.ts'):
+            errs = _validate_ts_syntax(fc, fk)
+            if errs:
+                syntax_issues[fk] = errs
+                all_errors.extend(errs)
+
+    # 3 — Step coverage
+    feature_content   = files.get(feature_key, "")
+    step_defs_content = files.get(step_key, "")
+    uncovered = _validate_step_coverage(feature_content, step_defs_content)
+    for step in uncovered:
+        all_warnings.append(f"No step definition matches: '{step}'")
+
+    return {
+        "valid":           len(all_errors) == 0,
+        "errors":          all_errors,
+        "warnings":        all_warnings,
+        "import_issues":   import_issues,
+        "syntax_issues":   syntax_issues,
+        "uncovered_steps": uncovered,
+    }
+
+
+# ============================================================================
+# scaffold_locator_repository
+# ============================================================================
+
+def _scaffold_locator_repository(
+    output_dir, enable_ai_vision, repository_path,
+    dashboard_port, enable_timing_healing, enable_visual_regression,
+    enable_devtools_healer=True, ai_healing_provider="anthropic",
+):
+    files = {
+        f"{output_dir}/LocatorHealer.ts":     _gen_locator_healer_cls(enable_ai_vision, enable_devtools_healer),
+        f"{output_dir}/LocatorRepository.ts": _gen_locator_repo_cls(repository_path),
+    }
+    if enable_timing_healing:
+        files[f"{output_dir}/TimingHealer.ts"] = _gen_timing_healer_cls(repository_path, dashboard_port)
+    if enable_visual_regression:
+        files[f"{output_dir}/VisualIntentChecker.ts"] = _gen_visual_checker_cls(repository_path, dashboard_port)
+    if enable_devtools_healer:
+        files[f"{output_dir}/DevToolsHealer.ts"] = _gen_devtools_healer_cls()
+    files[f"{output_dir}/HealingDashboard.ts"] = _gen_healing_dashboard_cls(repository_path, dashboard_port)
+
+    strategies = [
+        "1. Healed selector from LocatorRepository (zero overhead on repeat runs)",
+        "2. Primary CSS/data-testid selector",
+        "3. Role-based: page.getByRole() with intent keywords",
+        "4. Label-based: page.getByLabel() from intent string",
+        "5. Text-based: page.getByText() partial match",
+    ]
+    if enable_ai_vision:
+        strategies.append(
+            "6. playwright-cli snapshot → AI Vision (provider: anthropic | copilot | claude-code) "
+            "→ healed selector persisted  [skip with ENABLE_AI_HEALING=false]"
+        )
+    if enable_devtools_healer:
+        strategies.append("7. DevToolsHealer: CDPSession AX tree name match (no AI cost, no external process)")
+        strategies.append("8. DevToolsHealer: CDPSession bounding box spatial search at last known coordinates")
+    if enable_timing_healing:
+        strategies.append(f"+ TimingHealer: network trace drift detection → auto-adjusted timeouts → HealingDashboard :{dashboard_port}")
+    if enable_visual_regression:
+        strategies.append(f"+ VisualIntentChecker: element screenshot diff → baseline comparison → HealingDashboard :{dashboard_port}")
+    strategies.append(f"+ HealingDashboard: http://localhost:{dashboard_port} — review/approve all AI suggestions before commit")
+
+    return {
+        "files": files,
+        "output_dir": output_dir,
+        "repository_path": repository_path,
+        "dashboard_port": dashboard_port,
+        "dashboard_url": f"http://localhost:{dashboard_port}",
+        "healing_strategies": strategies,
+        "healing_layers": {
+            "locator":   "LocatorHealer.ts — selector chain + AI Vision (anthropic|copilot|claude-code, ENABLE_AI_HEALING=false to skip)",
+            "timing":    f"TimingHealer.ts — network drift auto-healing {'enabled' if enable_timing_healing else 'disabled'}",
+            "visual":    f"VisualIntentChecker.ts — screenshot regression {'enabled' if enable_visual_regression else 'disabled'}",
+            "devtools":  f"DevToolsHealer.ts — CDPSession AX tree + bounding box healing {'enabled' if enable_devtools_healer else 'disabled'}",
+            "dashboard": f"HealingDashboard.ts — http://localhost:{dashboard_port}",
+        },
+        "ai_healing_provider": ai_healing_provider if enable_ai_vision else "disabled",
+        "env_vars": {
+            "ENABLE_AI_HEALING":   "Set to 'false' to skip strategy 6 without disabling strategies 7 & 8.",
+            "AI_HEALING_PROVIDER": "Override provider at runtime: anthropic | copilot | claude-code.",
+            "AI_HEALING_API_KEY":  "Anthropic secret key — required when AI_HEALING_PROVIDER=anthropic.",
+            "GITHUB_TOKEN":        "GitHub Copilot token — required when AI_HEALING_PROVIDER=copilot.",
+            "ANTHROPIC_API_KEY":   "Set automatically by the claude CLI session (AI_HEALING_PROVIDER=claude-code).",
+        },
+        "note": (
+            "DevToolsHealer uses page.context().newCDPSession(page) at test runtime — "
+            "no external Chrome process or Playwright MCP connection needed during test execution."
+        ),
+    }
+
+
+def _gen_locator_healer_cls(enable_ai_vision, enable_devtools_healer=True):
+    ai_import  = 'import { execSync } from "child_process";' if enable_ai_vision else ""
+    cdp_import = 'import { DevToolsHealer } from "./DevToolsHealer";' if enable_devtools_healer else ""
+    cdp_field  = "  private devtools!: DevToolsHealer;" if enable_devtools_healer else ""
+    cdp_init   = ("    if ((this as any).devtools === undefined) "
+                  "(this as any).devtools = new DevToolsHealer(this.page, this.logger, this.repo);") if enable_devtools_healer else ""
+    cdp_call   = ("""
+    // Strategy 7: DevToolsHealer — AX tree name match via CDPSession (no AI cost)
+    const cdpAx = await this.devtools.findByAxName(key, intent, selector);
+    if (cdpAx) return cdpAx;
+    // Strategy 8: DevToolsHealer — bounding box spatial search via CDPSession
+    const cdpBb = await this.devtools.findByBoundingBox(key, this.repo.getBBox(key), intent);
+    if (cdpBb) return cdpBb;""") if enable_devtools_healer else ""
+
+    # ------------------------------------------------------------------
+    # AI Vision method — emitted only when enable_ai_vision=True.
+    #
+    # Runtime guard: ENABLE_AI_HEALING=false skips strategy 6 entirely
+    # so the full healing chain remains active in air-gapped / strict-CI
+    # environments without disabling strategies 7 & 8.
+    #
+    # Provider routing via AI_HEALING_PROVIDER:
+    #   "anthropic"    — direct Anthropic API (requires AI_HEALING_API_KEY)
+    #   "copilot"      — GitHub Copilot chat completions endpoint
+    #                    (uses GITHUB_TOKEN from the Copilot extension / CLI)
+    #   "claude-code"  — Claude Code local proxy (process.env.ANTHROPIC_API_KEY
+    #                    set automatically by `claude` CLI session)
+    #
+    # If AI_HEALING_PROVIDER is unset, "anthropic" is used and
+    # AI_HEALING_API_KEY must be present.  In Copilot / Claude Code mode
+    # no separate key is needed — the coding agent's session token is reused.
+    # ------------------------------------------------------------------
+    ai_method = """
+  // ── AI Vision provider routing ─────────────────────────────────────────
+  //
+  // Controlled by env vars — no code change needed to switch providers:
+  //
+  //   ENABLE_AI_HEALING=false          → skip strategy 6; fall through to 7 & 8
+  //   AI_HEALING_PROVIDER=anthropic    → direct Anthropic API (default)
+  //   AI_HEALING_PROVIDER=copilot      → GitHub Copilot chat completions
+  //   AI_HEALING_PROVIDER=claude-code  → Claude Code local proxy
+  //
+  // Provider auth:
+  //   anthropic   → AI_HEALING_API_KEY  (Anthropic secret key)
+  //   copilot     → GITHUB_TOKEN        (set by Copilot extension / gh auth login)
+  //   claude-code → ANTHROPIC_API_KEY   (set automatically by `claude` CLI session)
+  //
+  private _aiVisionEndpoint(): { url: string; authHeader: string; bodyMapper: (prompt: string) => object } {
+    const provider = (process.env.AI_HEALING_PROVIDER ?? "anthropic").toLowerCase();
+    if (provider === "copilot") {
+      // GitHub Copilot chat completions — reuses the coding agent's session token.
+      // Token is set by the Copilot VS Code extension or `gh auth login --scopes copilot`.
+      const token = process.env.GITHUB_TOKEN ?? "";
+      return {
+        url: "https://api.githubcopilot.com/chat/completions",
+        authHeader: `Bearer ${token}`,
+        bodyMapper: (prompt: string) => ({
+          model: "gpt-4o",
+          messages: [{ role: "user", content: prompt }],
+          max_tokens: 500,
+        }),
+      };
+    }
+    if (provider === "claude-code") {
+      // Claude Code sets ANTHROPIC_API_KEY automatically in its spawned shell.
+      // Uses the same Anthropic messages endpoint but authenticates via the
+      // coding agent's licence — no separate key needed at the project level.
+      const key = process.env.ANTHROPIC_API_KEY ?? "";
+      return {
+        url: "https://api.anthropic.com/v1/messages",
+        authHeader: `x-api-key ${key}`,
+        bodyMapper: (prompt: string) => ({
+          model: "claude-sonnet-4-20250514", max_tokens: 1000,
+          messages: [{ role: "user", content: prompt }],
+        }),
+      };
+    }
+    // Default: direct Anthropic API with explicit project key.
+    const key = process.env.AI_HEALING_API_KEY ?? process.env.ANTHROPIC_API_KEY ?? "";
+    return {
+      url: "https://api.anthropic.com/v1/messages",
+      authHeader: `x-api-key ${key}`,
+      bodyMapper: (prompt: string) => ({
+        model: "claude-sonnet-4-20250514", max_tokens: 1000,
+        messages: [{ role: "user", content: prompt }],
+      }),
+    };
+  }
+
+  private _extractSelector(provider: string, data: any): string {
+    // GitHub Copilot returns OpenAI-compatible response shape.
+    if (provider === "copilot") {
+      return (data.choices?.[0]?.message?.content ?? "").trim();
+    }
+    // Anthropic (direct or Claude Code proxy) returns content blocks.
+    return (data.content?.[0]?.text ?? "").trim();
+  }
+
+  private async healViaAiVision(key: string, intent: string): Promise<Locator> {
+    // ── Runtime guard — skip strategy 6 without disabling the full chain ──
+    if (process.env.ENABLE_AI_HEALING === "false") {
+      this.logger.info("⚕ AI Vision skipped (ENABLE_AI_HEALING=false)");
+      throw new Error(`LocatorHealer: strategy 6 disabled via ENABLE_AI_HEALING=false`);
+    }
+
+    const provider = (process.env.AI_HEALING_PROVIDER ?? "anthropic").toLowerCase();
+    this.logger.warn(`⚕ AI Vision [${provider}]: key="${key}" intent="${intent}"`);
+    try {
+      const snapshot = execSync("playwright-cli snapshot", { encoding: "utf8", timeout: 10_000 });
+      const { url, authHeader, bodyMapper } = this._aiVisionEndpoint();
+      const prompt = `DOM snapshot:\\n${snapshot.slice(0, 3500)}\\nFind: "${intent}". Return ONLY a CSS selector, no explanation.`;
+
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      // authHeader format is "<scheme> <token>" for Bearer, or "<header-name> <value>" for x-api-key
+      if (authHeader.startsWith("Bearer ")) {
+        headers["Authorization"] = authHeader;
+      } else if (authHeader.startsWith("x-api-key ")) {
+        headers["x-api-key"] = authHeader.slice("x-api-key ".length);
+        headers["anthropic-version"] = "2023-06-01";
+      }
+
+      const resp = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(bodyMapper(prompt)),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`AI Vision HTTP ${resp.status}: ${body.slice(0, 200)}`);
+      }
+      const data = await resp.json();
+      const sel = this._extractSelector(provider, data);
+      if (sel) {
+        const loc = this.page.locator(sel);
+        await loc.waitFor({ state: "attached", timeout: 5_000 });
+        this.repo.updateHealed(key, sel, intent, `ai-vision-${provider}`);
+        this.logger.info(`⚕ AI Vision healed [${provider}]: ${key} → ${sel}`);
+        return loc;
+      }
+    } catch (err) { this.logger.error(`⚕ AI Vision failed [${provider}]: ${err}`); }
+    throw new Error(`LocatorHealer: all strategies exhausted for key="${key}" intent="${intent}"`);
+  }
+""" if enable_ai_vision else """
+  private async healViaAiVision(key: string, intent: string): Promise<Locator> {
+    throw new Error(`LocatorHealer: all strategies exhausted for key="${key}" intent="${intent}"`);
+  }
+"""
+    return f'''import {{ Page, Locator }} from "@playwright/test";
+import {{ Logger }} from "winston";
+{ai_import}
+{cdp_import}
+import {{ LocatorRepository }} from "./LocatorRepository";
+
+/**
+ * LocatorHealer — Multi-Strategy Locator Healing
+ *
+ * Chain: cached-healed → primary → role → label → text →
+ *        AI Vision (6) → DevToolsHealer AX-name (7) → DevToolsHealer bbox (8)
+ *
+ * Strategies 7 & 8 use page.context().newCDPSession(page) — no external process.
+ *
+ * All healed selectors persisted in LocatorRepository (instant on repeat runs).
+ * Bounding boxes captured after every successful click for Strategy 8.
+ */
+export class LocatorHealer {{
+  private static readonly TIMEOUT   = 8_000;
+  private static readonly HEAL_TO   = 15_000;
+  private static readonly ATTACH_TO = 3_000;
+  {cdp_field}
+
+  constructor(
+    private readonly page:   Page,
+    private readonly logger: Logger,
+    private readonly repo:   LocatorRepository,
+  ) {{
+    {cdp_init}
+  }}
+
+  async clickWithHealing(key: string, selector: string, intent: string): Promise<void> {{
+    const loc = await this.resolve(key, selector, intent);
+    await loc.click({{ timeout: LocatorHealer.TIMEOUT }});
+    this.repo.incrementSuccess(key);
+    this.logger.info(`✓ click: ${{key}}`);
+    if ((this as any).devtools) await (this as any).devtools.captureBoundingBox(key, selector).catch(()=>{{}});
+  }}
+
+  async fillWithHealing(key: string, selector: string, value: string, intent: string): Promise<void> {{
+    const loc = await this.resolve(key, selector, intent);
+    await loc.fill(value, {{ timeout: LocatorHealer.TIMEOUT }});
+    this.repo.incrementSuccess(key);
+  }}
+
+  async assertVisibleWithHealing(key: string, selector: string, intent: string): Promise<void> {{
+    const loc = await this.resolve(key, selector, intent);
+    await loc.waitFor({{ state: "visible", timeout: LocatorHealer.HEAL_TO }});
+    this.logger.info(`✓ visible: ${{key}}`);
+  }}
+
+  async getTextWithHealing(key: string, selector: string, intent: string): Promise<string> {{
+    return (await (await this.resolve(key, selector, intent)).textContent()) ?? "";
+  }}
+
+  private async resolve(key: string, selector: string, intent: string): Promise<Locator> {{
+    const healed = this.repo.getHealed(key);
+    if (healed && healed !== selector) {{
+      try {{
+        const l = this.page.locator(healed);
+        await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+        return l;
+      }} catch {{}}
+    }}
+    try {{
+      const l = this.page.locator(selector);
+      await l.waitFor({{ state: "attached", timeout: 5_000 }});
+      return l;
+    }} catch {{
+      this.logger.warn(`⚕ Primary failed: ${{key}}`);
+      this.repo.incrementFailure(key);
+    }}
+    const words = intent.split(" ").slice(0, 3).join("|");
+    for (const role of ["button", "link", "textbox", "combobox"] as const) {{
+      try {{
+        const l = this.page.getByRole(role, {{ name: new RegExp(words, "i") }});
+        await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+        this.repo.updateHealed(key, `[role:${{role}}]`, intent, "role");
+        this.logger.warn(`⚕ Role-healed: ${{key}}`);
+        return l;
+      }} catch {{}}
+    }}
+    try {{
+      const l = this.page.getByLabel(intent, {{ exact: false }});
+      await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+      this.repo.updateHealed(key, "[label-healed]", intent, "label");
+      return l;
+    }} catch {{}}
+    try {{
+      const w = intent.split(" ").find(w => w.length > 3) ?? intent;
+      const l = this.page.getByText(w, {{ exact: false }});
+      await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+      this.repo.updateHealed(key, "[text-healed]", intent, "text");
+      return l;
+    }} catch {{}}
+    {cdp_call}
+    return this.healViaAiVision(key, intent);
+  }}
+{ai_method}
+}}
+'''
+
+
+def _gen_locator_repo_cls(repository_path):
+    return f'''import * as fs from "fs";
+import * as path from "path";
+
+export interface BoundingBox {{ x:number; y:number; width:number; height:number; }}
+
+export interface LocatorEntry {{
+  selector: string; intent: string; stability?: number; healedSelector?: string;
+  healingHistory: Array<{{ from:string; to:string; timestamp:string; strategy:string }}>;
+  lastHealed?: string; successCount: number; failureCount: number;
+  /** Bounding box from last successful action — used by DevToolsHealer.findByBoundingBox */
+  lastBoundingBox?: BoundingBox;
+  /** Pending AI suggestion awaiting HealingDashboard approval before commit */
+  pendingSuggestion?: {{ selector:string; strategy:string; suggestedAt:string }};
+}}
+
+/**
+ * LocatorRepository — Shared state store for all healing layers.
+ * Persists to "{repository_path}".
+ * queueSuggestion / approveSuggestion / rejectSuggestion power the HealingDashboard.
+ */
+export class LocatorRepository {{
+  private readonly store = new Map<string, LocatorEntry>();
+  constructor(private readonly filePath = "{repository_path}") {{ this.load(); }}
+
+  register(key: string, selector: string, intent: string, stability = 0): void {{
+    if (!this.store.has(key))
+      this.store.set(key, {{ selector, intent, stability, healingHistory: [], successCount: 0, failureCount: 0 }});
+    else {{ this.store.get(key)!.intent = intent; this.store.get(key)!.stability = stability; }}
+  }}
+
+  getHealed(key: string): string | undefined {{ return this.store.get(key)?.healedSelector; }}
+
+  updateHealed(key: string, sel: string, intent: string, strategy = "unknown"): void {{
+    const e = this.store.get(key); if (!e) return;
+    e.healingHistory.push({{ from: e.healedSelector ?? e.selector, to: sel,
+                             timestamp: new Date().toISOString(), strategy }});
+    e.healedSelector = sel; e.lastHealed = new Date().toISOString();
+    delete e.pendingSuggestion; this.persist();
+  }}
+
+  queueSuggestion(key: string, suggestedSelector: string, strategy: string): void {{
+    const e = this.store.get(key); if (!e) return;
+    e.pendingSuggestion = {{ selector: suggestedSelector, strategy, suggestedAt: new Date().toISOString() }};
+    this.persist();
+  }}
+
+  approveSuggestion(key: string): boolean {{
+    const e = this.store.get(key);
+    if (!e?.pendingSuggestion) return false;
+    this.updateHealed(key, e.pendingSuggestion.selector, e.intent,
+                      e.pendingSuggestion.strategy + ":approved");
+    return true;
+  }}
+
+  rejectSuggestion(key: string): boolean {{
+    const e = this.store.get(key);
+    if (!e?.pendingSuggestion) return false;
+    delete e.pendingSuggestion; this.persist(); return true;
+  }}
+
+  updateBoundingBox(key: string, bbox: BoundingBox): void {{
+    const e = this.store.get(key);
+    if (e) {{ e.lastBoundingBox = bbox; this.persist(); }}
+  }}
+  getBBox(key: string): BoundingBox | null {{
+    return this.store.get(key)?.lastBoundingBox ?? null;
+  }}
+
+  getPendingSuggestions() {{
+    return [...this.store.entries()]
+      .filter(([, v]) => v.pendingSuggestion)
+      .map(([k, v]) => ({{ key: k, ...v }}));
+  }}
+
+  incrementSuccess(key: string) {{ const e=this.store.get(key); if(e) {{ e.successCount++; this.persist(); }} }}
+  incrementFailure(key: string) {{ const e=this.store.get(key); if(e) {{ e.failureCount++; this.persist(); }} }}
+
+  getAnalytics() {{
+    const entries = [...this.store.entries()];
+    return {{
+      totalLocators:    entries.length,
+      healedLocators:   entries.filter(([, v]) => v.healedSelector).length,
+      pendingApprovals: entries.filter(([, v]) => v.pendingSuggestion).length,
+      mostHealedKeys:   entries
+        .sort(([, a], [, b]) => b.healingHistory.length - a.healingHistory.length)
+        .slice(0, 10)
+        .map(([k, v]) => ({{ key: k, healCount: v.healingHistory.length, intent: v.intent }})),
+    }};
+  }}
+
+  exportJson(): string {{
+    const o: Record<string, LocatorEntry> = {{}};
+    this.store.forEach((v, k) => {{ o[k] = v; }});
+    return JSON.stringify(o, null, 2);
+  }}
+
+  private persist(): void {{
+    try {{
+      fs.mkdirSync(path.dirname(this.filePath), {{ recursive: true }});
+      fs.writeFileSync(this.filePath, this.exportJson(), "utf8");
+    }} catch {{}}
+  }}
+
+  private load(): void {{
+    try {{
+      if (fs.existsSync(this.filePath)) {{
+        const raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+        Object.entries(raw).forEach(([k, v]) => this.store.set(k, v as LocatorEntry));
+      }}
+    }} catch {{}}
+  }}
+}}
+'''
+
+
+def _gen_timing_healer_cls(repository_path, dashboard_port):
+    return f'''import {{ Page }} from "@playwright/test";
+import {{ Logger }} from "winston";
+import {{ LocatorRepository }} from "./LocatorRepository";
+
+/**
+ * TimingHealer — Layer 2: Network Trace Timing Healing
+ *
+ * When an endpoint drifts > 20% from baseline, auto-adjusts timeout for the
+ * current run and queues a suggestion to HealingDashboard :{dashboard_port}.
+ */
+export class TimingHealer {{
+  private static readonly HEADROOM        = 1.5;
+  private static readonly DRIFT_THRESHOLD = 0.2;
+  private static readonly MAX_TIMEOUT     = 60_000;
+  private readonly observations           = new Map<string, number[]>();
+
+  constructor(
+    private readonly page:   Page,
+    private readonly logger: Logger,
+    private readonly repo:   LocatorRepository,
+  ) {{}}
+
+  async waitForNetworkIdle(actionKey: string, baselineMs = 10_000): Promise<void> {{
+    const adjusted = this._adjusted(actionKey, baselineMs);
+    const start    = Date.now();
+    try {{
+      await this.page.waitForLoadState("networkidle", {{ timeout: adjusted }});
+    }} catch {{
+      this.logger.warn(`⏱ TimingHealer: networkidle timeout for "${{actionKey}}" (${{adjusted}}ms)`);
+    }}
+    this._record(actionKey, Date.now() - start, baselineMs);
+  }}
+
+  async waitForApiResponse(
+    actionKey: string, urlPattern: string | RegExp, baselineMs = 15_000,
+  ): Promise<void> {{
+    const adjusted = this._adjusted(actionKey, baselineMs);
+    const start    = Date.now();
+    try {{
+      await this.page.waitForResponse(
+        r => typeof urlPattern === "string"
+          ? r.url().includes(urlPattern)
+          : urlPattern.test(r.url()),
+        {{ timeout: adjusted }},
+      );
+    }} catch {{
+      this.logger.warn(`⏱ TimingHealer: API timeout for "${{actionKey}}"`);
+    }}
+    this._record(actionKey, Date.now() - start, baselineMs);
+  }}
+
+  private _adjusted(actionKey: string, defaultMs: number): number {{
+    const obs = this.observations.get(actionKey);
+    if (!obs?.length) return defaultMs;
+    const last = obs[obs.length - 1];
+    return Math.min(Math.ceil(last * TimingHealer.HEADROOM), TimingHealer.MAX_TIMEOUT);
+  }}
+
+  private _record(actionKey: string, observedMs: number, baselineMs: number): void {{
+    const obs = this.observations.get(actionKey) ?? [];
+    obs.push(observedMs);
+    this.observations.set(actionKey, obs.slice(-20));
+    const drift = (observedMs - baselineMs) / baselineMs;
+    if (drift > TimingHealer.DRIFT_THRESHOLD) {{
+      const adjusted = Math.min(Math.ceil(observedMs * TimingHealer.HEADROOM), TimingHealer.MAX_TIMEOUT);
+      this.logger.warn(
+        `⏱ TimingHealer: "${{actionKey}}" drifted ${{Math.round(drift * 100)}}% ` +
+        `(${{baselineMs}}ms → ${{observedMs}}ms). Auto-adjusted to ${{adjusted}}ms. ` +
+        `Queued for engineer review at http://localhost:{dashboard_port}`,
+      );
+      this.repo.queueSuggestion(`timing:${{actionKey}}`, `timeout:${{adjusted}}`, "timing-drift");
+    }}
+  }}
+}}
+'''
+
+
+def _gen_visual_checker_cls(repository_path, dashboard_port):
+    return f'''import {{ Page, expect }} from "@playwright/test";
+import {{ Logger }} from "winston";
+import * as fs   from "fs";
+import * as path from "path";
+import {{ LocatorRepository }} from "./LocatorRepository";
+
+/**
+ * VisualIntentChecker — Layer 3: Visual Regression alongside Locator Healing
+ *
+ * Captures element screenshots at assertions and diffs against approved baselines.
+ * Pixel diff > 0.5% → queued to HealingDashboard :{dashboard_port}.
+ */
+export class VisualIntentChecker {{
+  private static readonly DIFF_THRESHOLD = 0.5;
+  private readonly baselineDir: string;
+  private readonly actualDir:   string;
+
+  constructor(
+    private readonly page:   Page,
+    private readonly logger: Logger,
+    private readonly repo?:  LocatorRepository,
+  ) {{
+    this.baselineDir = path.join("test-results", "visual-baselines");
+    this.actualDir   = path.join("test-results", "visual-actuals");
+    fs.mkdirSync(this.baselineDir, {{ recursive: true }});
+    fs.mkdirSync(this.actualDir,   {{ recursive: true }});
+  }}
+
+  async check(key: string, selector: string, intent: string): Promise<void> {{
+    const safe     = key.replace(/[^a-z0-9_-]/gi, "_");
+    const baseline = path.join(this.baselineDir, `${{safe}}.png`);
+    const actual   = path.join(this.actualDir,   `${{safe}}.png`);
+    try {{
+      const loc = this.page.locator(selector).first();
+      if ((await loc.count()) === 0) {{
+        this.logger.warn(`📸 VisualIntent: element not found for "${{key}}" — skipping`);
+        return;
+      }}
+      const screenshot = await loc.screenshot({{ timeout: 5_000 }});
+      fs.writeFileSync(actual, screenshot);
+      if (!fs.existsSync(baseline)) {{
+        fs.copyFileSync(actual, baseline);
+        this.logger.info(`📸 VisualIntent: new baseline saved for "${{key}}"`);
+        return;
+      }}
+      await expect(loc).toHaveScreenshot(`${{safe}}.png`, {{
+        maxDiffPixelRatio: VisualIntentChecker.DIFF_THRESHOLD / 100,
+        threshold: 0.2,
+      }});
+      this.logger.info(`📸 VisualIntent: ${{key}} — passed`);
+    }} catch {{
+      this.logger.warn(
+        `📸 VisualIntent: "${{key}}" visual regression detected! ` +
+        `Queued for review at http://localhost:{dashboard_port}`,
+      );
+      this.repo?.queueSuggestion(`visual:${{key}}`, actual, `visual-regression:${{intent}}`);
+    }}
+  }}
+
+  approveBaseline(key: string): void {{
+    const safe     = key.replace(/[^a-z0-9_-]/gi, "_");
+    const baseline = path.join(this.baselineDir, `${{safe}}.png`);
+    const actual   = path.join(this.actualDir,   `${{safe}}.png`);
+    if (fs.existsSync(actual)) {{
+      fs.copyFileSync(actual, baseline);
+      this.logger.info(`📸 Baseline updated for "${{key}}"`);
+    }}
+  }}
+}}
+'''
+
+
+def _gen_healing_dashboard_cls(repository_path, dashboard_port):
+    return f'''import * as fs   from "fs";
+import * as path from "path";
+import * as http from "http";
+import * as url  from "url";
+
+/**
+ * HealingDashboard — CI/CD Telemetry for AI-Suggested Changes
+ *
+ * Zero-dependency HTTP server displaying all pending suggestions from:
+ *   • LocatorHealer  → AI Vision selector suggestions
+ *   • TimingHealer   → auto-adjusted timeout suggestions
+ *   • VisualIntentChecker → visual baseline update suggestions
+ *
+ * Endpoints:
+ *   GET  /                  → HTML dashboard (auto-refreshes every 10s)
+ *   GET  /api/pending       → JSON pending suggestions
+ *   GET  /api/analytics     → JSON healing analytics
+ *   POST /api/approve/:key  → Approve → commit to {repository_path}
+ *   POST /api/reject/:key   → Reject → discard
+ *   GET  /api/visual/:key   → Serve actual PNG for visual diff review
+ *
+ * Set HEALING_DASHBOARD_PORT=0 to disable the HTTP server in CI pipelines.
+ * Suggestions are still written to {repository_path} for async review.
+ */
+export class HealingDashboard {{
+  private server: http.Server | null = null;
+  private readonly port: number;
+
+  constructor(
+    private readonly repoPath = "{repository_path}",
+    port = {dashboard_port},
+  ) {{
+    this.port = Number(process.env.HEALING_DASHBOARD_PORT ?? port);
+  }}
+
+  start(): void {{
+    if (this.port === 0) return;
+    this.server = http.createServer((req, res) => this._route(req, res));
+    this.server.listen(this.port, () => {{
+      console.log(`\\n🩺 HealingDashboard running at http://localhost:${{this.port}}`);
+      console.log(`   Approve or reject AI-suggested changes before committing.\\n`);
+    }});
+  }}
+
+  stop(): void {{ this.server?.close(); }}
+
+  private _route(req: http.IncomingMessage, res: http.ServerResponse): void {{
+    const p = url.parse(req.url ?? "/").pathname ?? "/";
+    const m = req.method ?? "GET";
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    if (m === "OPTIONS") {{ res.writeHead(204); res.end(); return; }}
+
+    if (m === "GET"  && p === "/")              {{ res.writeHead(200, {{"Content-Type":"text/html"}}); res.end(this._html()); return; }}
+    if (m === "GET"  && p === "/api/pending")   {{ res.writeHead(200, {{"Content-Type":"application/json"}}); res.end(JSON.stringify(this._pending(), null, 2)); return; }}
+    if (m === "GET"  && p === "/api/analytics") {{ res.writeHead(200, {{"Content-Type":"application/json"}}); res.end(JSON.stringify(this._analytics(), null, 2)); return; }}
+
+    const am = p.match(/^[/]api[/](approve|reject)[/](.+)$/);
+    if (m === "POST" && am) {{
+      const ok = am[1] === "approve"
+        ? this._approve(decodeURIComponent(am[2]))
+        : this._reject(decodeURIComponent(am[2]));
+      res.writeHead(ok ? 200 : 404, {{"Content-Type":"application/json"}});
+      res.end(JSON.stringify({{ success: ok }}));
+      return;
+    }}
+
+    const vm = p.match(/^[/]api[/]visual[/](.+)$/);
+    if (m === "GET" && vm) {{
+      const key = decodeURIComponent(vm[1]).replace("visual:", "");
+      const img = path.join("test-results", "visual-actuals", `${{key}}.png`);
+      if (fs.existsSync(img)) {{ res.writeHead(200, {{"Content-Type":"image/png"}}); res.end(fs.readFileSync(img)); }}
+      else {{ res.writeHead(404); res.end("Not found"); }}
+      return;
+    }}
+    res.writeHead(404); res.end("Not found");
+  }}
+
+  private _load(): Record<string, any> {{
+    try {{ return JSON.parse(fs.readFileSync(this.repoPath, "utf8")); }} catch {{ return {{}}; }}
+  }}
+  private _save(d: Record<string, any>): void {{
+    fs.mkdirSync(path.dirname(this.repoPath), {{ recursive: true }});
+    fs.writeFileSync(this.repoPath, JSON.stringify(d, null, 2), "utf8");
+  }}
+
+  private _pending(): any[] {{
+    return Object.entries(this._load())
+      .filter(([, v]) => (v as any).pendingSuggestion)
+      .map(([k, v]) => {{
+        const vv = v as any;
+        return {{
+          key: k, intent: vv.intent,
+          current: vv.healedSelector ?? vv.selector,
+          suggestion: vv.pendingSuggestion,
+          failureCount: vv.failureCount,
+          healCount: vv.healingHistory.length,
+        }};
+      }});
+  }}
+
+  private _analytics(): any {{
+    const e = Object.entries(this._load());
+    return {{
+      totalLocators:    e.length,
+      healedLocators:   e.filter(([, v]) => (v as any).healedSelector).length,
+      pendingApprovals: e.filter(([, v]) => (v as any).pendingSuggestion).length,
+      timingSuggestions: e.filter(([k]) => k.startsWith("timing:")).length,
+      visualSuggestions: e.filter(([k]) => k.startsWith("visual:")).length,
+      mostHealedKeys:   e
+        .sort(([, a], [, b]) => (b as any).healingHistory.length - (a as any).healingHistory.length)
+        .slice(0, 10)
+        .map(([k, v]) => ({{ key: k, healCount: (v as any).healingHistory.length, intent: (v as any).intent }})),
+    }};
+  }}
+
+  private _approve(key: string): boolean {{
+    const d = this._load(); const e = d[key];
+    if (!e?.pendingSuggestion) return false;
+    e.healingHistory.push({{
+      from: e.healedSelector ?? e.selector, to: e.pendingSuggestion.selector,
+      timestamp: new Date().toISOString(), strategy: e.pendingSuggestion.strategy + ":dashboard-approved",
+    }});
+    e.healedSelector = e.pendingSuggestion.selector;
+    delete e.pendingSuggestion;
+    this._save(d);
+    console.log(`✅ HealingDashboard: approved "${{key}}"`);
+    return true;
+  }}
+
+  private _reject(key: string): boolean {{
+    const d = this._load(); const e = d[key];
+    if (!e?.pendingSuggestion) return false;
+    console.log(`❌ HealingDashboard: rejected "${{key}}"`);
+    delete e.pendingSuggestion;
+    this._save(d);
+    return true;
+  }}
+
+  private _html(): string {{
+    const pending   = this._pending();
+    const analytics = this._analytics();
+    const rows = pending.map(p => `
+      <tr>
+        <td><code>${{p.key}}</code></td>
+        <td>${{p.intent}}</td>
+        <td><code style="color:#888">${{p.current}}</code></td>
+        <td><code style="color:#f59e0b">${{p.suggestion.selector}}</code></td>
+        <td>${{p.suggestion.strategy}}</td>
+        <td><small>${{new Date(p.suggestion.suggestedAt).toLocaleString()}}</small></td>
+        <td>
+          <button onclick="act('approve','${{enc(p.key)}}')" style="background:#22c55e;color:#000;border:none;padding:4px 10px;border-radius:3px;cursor:pointer">Approve</button>
+          <button onclick="act('reject','${{enc(p.key)}}')"  style="background:#ef4444;color:#fff;border:none;padding:4px 10px;border-radius:3px;cursor:pointer;margin-left:4px">Reject</button>
+          ${{p.key.startsWith("visual:") ? `<a href="/api/visual/${{enc(p.key)}}" target="_blank" style="color:#818cf8;margin-left:6px">View diff</a>` : ""}}
+        </td>
+      </tr>`).join("");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8"><title>🩺 Healing Dashboard</title>
+  <meta http-equiv="refresh" content="10">
+  <style>
+    body {{ font-family: monospace; background:#0f172a; color:#e2e8f0; padding:24px }}
+    h1   {{ color:#38bdf8; margin-bottom:4px }}
+    .sub {{ color:#64748b; font-size:12px; display:block; margin-bottom:20px }}
+    .stats {{ display:flex; gap:12px; margin-bottom:20px }}
+    .stat {{ background:#1e293b; border:1px solid #334155; border-radius:6px; padding:10px 16px }}
+    .sv  {{ font-size:26px; font-weight:700; color:#38bdf8 }}
+    .sl  {{ font-size:9px; color:#64748b; letter-spacing:1px }}
+    table{{ width:100%; border-collapse:collapse; background:#1e293b; border-radius:6px; overflow:hidden }}
+    th   {{ background:#0f172a; padding:9px 12px; font-size:9px; letter-spacing:1px; color:#64748b; text-align:left }}
+    td   {{ padding:9px 12px; border-bottom:1px solid #334155; font-size:11px }}
+  </style>
+</head>
+<body>
+  <h1>🩺 Healing Dashboard</h1>
+  <span class="sub">
+    Auto-refreshes every 10s &middot;
+    <a href="/api/analytics" style="color:#818cf8">Analytics JSON</a> &middot;
+    Approve or reject AI suggestions before they are committed to the repository
+  </span>
+  <div class="stats">
+    <div class="stat"><div class="sv">${{analytics.pendingApprovals}}</div><div class="sl">PENDING</div></div>
+    <div class="stat"><div class="sv">${{analytics.healedLocators}}</div><div class="sl">HEALED</div></div>
+    <div class="stat"><div class="sv">${{analytics.timingSuggestions}}</div><div class="sl">TIMING</div></div>
+    <div class="stat"><div class="sv">${{analytics.visualSuggestions}}</div><div class="sl">VISUAL</div></div>
+  </div>
+  <table>
+    <thead>
+      <tr><th>Key</th><th>Intent</th><th>Current</th><th>Suggested</th><th>Strategy</th><th>Time</th><th>Action</th></tr>
+    </thead>
+    <tbody>
+      ${{rows || '<tr><td colspan="7" style="padding:24px;text-align:center;color:#64748b">✓ No pending suggestions — all AI changes approved or no healing events yet</td></tr>'}}
+    </tbody>
+  </table>
+  <script>
+    function enc(s) {{ return encodeURIComponent(s); }}
+    async function act(action, key) {{
+      await fetch("/api/" + action + "/" + key, {{ method: "POST" }});
+      location.reload();
+    }}
+  </script>
+</body>
+</html>`;
+  }}
+}}
+'''
+
+
+def _gen_devtools_healer_cls() -> str:
+    return r'''import { Page, Locator } from "@playwright/test";
+import { Logger } from "winston";
+import { LocatorRepository, BoundingBox } from "./LocatorRepository";
+
+interface AXNode {
+  role?: { value: string };
+  name?: { value: string };
+  backendDOMNodeId?: number;
+}
+
+/**
+ * DevToolsHealer — CDP-Powered Precision Healing (Layer 4, runtime only)
+ *
+ * Uses page.context().newCDPSession(page) — no external process, no Playwright MCP
+ * connection, no Chrome debugging port. Works purely within the Playwright test runner
+ * on Chromium-based browsers.
+ *
+ * Three modes:
+ *
+ * Mode A — findByAxName: walks Accessibility.getFullAXTree for a node whose
+ *   accessible name matches the intent string (≥60% word overlap). Resolves the
+ *   best stable selector and validates with DOM.querySelectorAll.
+ *
+ * Mode B — findByBoundingBox: finds the element now at the last known screen
+ *   coordinates (DOM.getNodeForLocation). Handles re-keyed elements whose layout
+ *   position is unchanged.
+ *
+ * Mode C — validateSelector: used by generate_playwright_code at generation time
+ *   to confirm a proposed selector matches exactly 1 element. Not called at runtime.
+ *   (Note: generation-time validation now uses Playwright MCP browser_snapshot
+ *    to derive selectors from the AX tree directly — this method is a runtime-only
+ *    fallback validator.)
+ *
+ * Selector stability ranking (_bestSelectorForNode):
+ *   data-testid (100) > aria-role+aria-label (90) > id (80) > aria-label (70) > placeholder (60)
+ */
+export class DevToolsHealer {
+  private cdpSession: any | null = null;
+
+  constructor(
+    private readonly page:   Page,
+    private readonly logger: Logger,
+    private readonly repo:   LocatorRepository,
+  ) {}
+
+  async findByAxName(key: string, intent: string, _primarySelector: string): Promise<Locator | null> {
+    const cdp = await this._session();
+    if (!cdp) return null;
+
+    try {
+      const result = await cdp.send("Accessibility.getFullAXTree", {}) as { nodes: AXNode[] };
+      const intentWords = intent.toLowerCase().split(" ").filter(w => w.length > 2);
+
+      for (const node of result.nodes ?? []) {
+        const nodeName = (node.name?.value ?? "").toLowerCase();
+        const nodeRole = (node.role?.value ?? "").toLowerCase();
+        const matches  = intentWords.filter(w => nodeName.includes(w)).length;
+        if (matches < Math.ceil(intentWords.length * 0.6)) continue;
+
+        const selector = await this._bestSelectorForNode(cdp, node.backendDOMNodeId, nodeRole, node.name?.value ?? "");
+        if (!selector) continue;
+
+        const validated = await this.validateSelector(selector);
+        if (!validated) continue;
+
+        const loc = this.page.locator(selector);
+        this.repo.updateHealed(key, selector, intent, "cdp-ax-name");
+        this.logger.info(`⚕ DevToolsHealer (AX): ${key} → ${selector}`);
+        return loc;
+      }
+    } catch (err) {
+      this.logger.warn(`⚕ DevToolsHealer AX failed: ${err}`);
+    }
+    return null;
+  }
+
+  async findByBoundingBox(key: string, bbox: BoundingBox | null, intent: string): Promise<Locator | null> {
+    if (!bbox) return null;
+    const cdp = await this._session();
+    if (!cdp) return null;
+
+    try {
+      const cx = Math.round(bbox.x + bbox.width  / 2);
+      const cy = Math.round(bbox.y + bbox.height / 2);
+
+      const result = await cdp.send("DOM.getNodeForLocation", {
+        x: cx, y: cy, includeUserAgentShadowDOM: false,
+      }) as { backendNodeId?: number };
+
+      if (!result.backendNodeId) return null;
+
+      const selector = await this._bestSelectorForNode(cdp, result.backendNodeId, "", intent);
+      if (!selector) return null;
+
+      const validated = await this.validateSelector(selector);
+      if (!validated) return null;
+
+      const loc = this.page.locator(selector);
+      this.repo.updateHealed(key, selector, intent, "cdp-bounding-box");
+      this.logger.info(`⚕ DevToolsHealer (BBox): ${key} → ${selector} at (${cx},${cy})`);
+      return loc;
+    } catch (err) {
+      this.logger.warn(`⚕ DevToolsHealer BBox failed: ${err}`);
+    }
+    return null;
+  }
+
+  async validateSelector(selector: string): Promise<boolean> {
+    const cdp = await this._session();
+    if (!cdp) return true;
+
+    try {
+      const result = await cdp.send("Runtime.evaluate", {
+        expression: `document.querySelectorAll(${JSON.stringify(selector)}).length`,
+        returnByValue: true,
+      }) as { result: { value: number } };
+      const count = result?.result?.value ?? 0;
+      if (count !== 1) {
+        this.logger.warn(`⚕ DevToolsHealer: selector "${selector}" matched ${count} elements (expected 1)`);
+      }
+      return count === 1;
+    } catch {
+      return true;
+    }
+  }
+
+  async captureBoundingBox(key: string, selector: string): Promise<void> {
+    const cdp = await this._session();
+    if (!cdp) return;
+
+    try {
+      const nodeResult = await cdp.send("DOM.querySelector", {
+        nodeId: 1,
+        selector,
+      }) as { nodeId: number };
+
+      if (!nodeResult.nodeId) return;
+
+      const boxResult = await cdp.send("DOM.getBoxModel", {
+        nodeId: nodeResult.nodeId,
+      }) as { model?: { content: number[] } };
+
+      const content = boxResult?.model?.content ?? [];
+      if (content.length >= 6) {
+        const bbox: BoundingBox = {
+          x: content[0], y: content[1],
+          width: content[4] - content[0],
+          height: content[5] - content[1],
+        };
+        this.repo.updateBoundingBox(key, bbox);
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  private async _session(): Promise<any | null> {
+    if (this.cdpSession) return this.cdpSession;
+    try {
+      this.cdpSession = await (this.page.context() as any).newCDPSession(this.page);
+      return this.cdpSession;
+    } catch {
+      return null; // non-Chromium browser
+    }
+  }
+
+  private async _bestSelectorForNode(
+    cdp: any, backendNodeId: number | undefined,
+    role: string, name: string,
+  ): Promise<string | null> {
+    if (!backendNodeId) return null;
+
+    try {
+      const resolve = await cdp.send("DOM.resolveNode", { backendNodeId }) as { object?: { objectId: string } };
+      const objId = resolve?.object?.objectId;
+      if (!objId) return null;
+
+      const props = await cdp.send("Runtime.callFunctionOn", {
+        objectId: objId,
+        functionDeclaration: `function() {
+          const e = this;
+          return JSON.stringify({
+            testid:     e.getAttribute('data-testid') || e.getAttribute('data-test-id') || e.getAttribute('data-cy'),
+            ariaLabel:  e.getAttribute('aria-label'),
+            id:         e.id,
+            placeholder:e.getAttribute('placeholder'),
+          });
+        }`,
+        returnByValue: true,
+      }) as { result?: { value: string } };
+
+      const attrs = JSON.parse(props?.result?.value ?? "{}");
+
+      if (attrs.testid)     return `[data-testid='${attrs.testid}']`;
+      if (attrs.ariaLabel)  return `[aria-label='${attrs.ariaLabel}']`;
+      if (attrs.id && !/^\d/.test(attrs.id)) return `#${attrs.id}`;
+      if (attrs.placeholder)return `[placeholder='${attrs.placeholder}']`;
+      if (role && name)     return `[role='${role}'][aria-label='${name}']`;
+    } catch { /* fall through */ }
+
+    return null;
+  }
+}
+'''
+
+
+# ============================================================================
+# Entry point
+# ============================================================================
+
+async def _run():
+    async with stdio_server() as (r, w):
+        await app.run(r, w, app.create_initialization_options())
+
+
+def main():
+    try:
+        get_auth_headers()
+    except Exception as e:
+        print(f"[qa-playwright-generator] Auth error: {e}", file=sys.stderr)
+        sys.exit(1)
+    user = get_signed_in_user()
+    if user:
+        print(f"[qa-playwright-generator] Authenticated as: {user}", file=sys.stderr)
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()