synapse-hub 0.0.0-stage → 2.0.0

package/tools/safety_firewall.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""
+Enterprise Action Safety Firewall & Blast Radius Containment Engine
+--------------------------------------------------------------------
+Prevents AI agents and test runners from executing catastrophic or irreversible
+actions on Live/Staging/UAT environments (e.g. Delete All, Purge, Wipe, Pay, Drop).
+
+Supports:
+  - Direct action checking (--action, --text, --selector)
+  - Code snippet and script inspection (--code, --file)
+  - Pipeline stdin stream inspection (e.g. echo 'page.click(...)' | python safety_firewall.py --dry-run)
+  - Pre-execution validation hooks before Playwright/CDP browser dispatch
+"""
+
+import os
+import re
+import sys
+import json
+import argparse
+from typing import List, Dict, Any, Tuple
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+DANGEROUS_ACTION_KEYWORDS = [
+    r"\bdelete\b",
+    r"\bremove\b",
+    r"\bpurge\b",
+    r"\bwipe\b",
+    r"\bdrop\b",
+    r"\bpay\b",
+    r"\bpurchase\b",
+    r"\bcheckout\b",
+    r"\bterminate\b",
+    r"\bdestroy\b",
+    r"\breset\b",
+    r"\btransfer\b",
+    r"\bformat\b",
+]
+
+DANGEROUS_SELECTOR_PATTERNS = [
+    r"\[data-action\*=['\"]?delete['\"]?\]",
+    r"\[data-action\*=['\"]?pay['\"]?\]",
+    r"\.btn-danger\b",
+    r"\.p-button-danger\b",
+    r"\[aria-label\*=['\"]?delete['\"]?\]",
+    r"button[#\.\-_a-zA-Z0-9]*[_\-]*(?:del|delete|purge|remove|wipe|drop)",
+]
+
+COMPILED_TEXT_REGEX = re.compile("|".join(DANGEROUS_ACTION_KEYWORDS), re.IGNORECASE)
+COMPILED_SEL_REGEX = re.compile("|".join(DANGEROUS_SELECTOR_PATTERNS), re.IGNORECASE)
+
+# Pattern to extract interaction statements from Playwright / Selenium / Groovy
+INTERACTION_CODE_PATTERNS = [
+    # page.click('selector'), page.fill('selector', 'val')
+    re.compile(r"""(?:page|frame)\.(?P<act>click|dblclick|fill|type|press|check)\s*\(\s*['"](?P<sel>[^'"]+)['"](?:\s*,\s*['"](?P<text>[^'"]*)['"])?""", re.IGNORECASE),
+    # page.locator('selector').click()
+    re.compile(r"""(?:page|frame)\.locator\s*\(\s*['"](?P<sel>[^'"]+)['"]\s*\)\.(?P<act>click|fill|press)""", re.IGNORECASE),
+    # page.getByText('text').click()
+    re.compile(r"""(?:page|frame)\.getByText\s*\(\s*['"](?P<text>[^'"]+)['"]\s*\)\.(?P<act>click)""", re.IGNORECASE),
+    # page.getByRole('button', { name: 'Delete' }).click()
+    re.compile(r"""(?:page|frame)\.getByRole\s*\(\s*['"](?P<role>[^'"]+)['"]\s*,\s*\{[^}]*name:\s*['"](?P<text>[^'"]+)['"]""", re.IGNORECASE),
+    # WebUI.click(findTestObject(...)) or WebUI.clickOffset
+    re.compile(r"""WebUI\.(?P<act>click|setText)\s*\([^)]*['"](?P<sel>[^'"]*)['"]""", re.IGNORECASE),
+]
+
+
+def is_action_dangerous(action_type: str, text: str = "", selector: str = "") -> Tuple[bool, str]:
+    """
+    Evaluates whether an intended action touches a dangerous or irreversible UI element.
+    Returns (is_dangerous: bool, reason: str).
+    """
+    text_clean = text.strip() if text else ""
+    sel_clean = selector.strip() if selector else ""
+
+    # Check text content
+    if text_clean and COMPILED_TEXT_REGEX.search(text_clean):
+        match = COMPILED_TEXT_REGEX.search(text_clean).group(0)
+        return True, f"Element text contains dangerous keyword: '{match}'"
+
+    # Check selector
+    if sel_clean and COMPILED_SEL_REGEX.search(sel_clean):
+        return True, f"Element selector matches destructive pattern: '{sel_clean}'"
+
+    # Specific dangerous action types
+    if action_type.lower() in ("drop_database", "wipe_environment", "execute_payment"):
+        return True, f"Action type '{action_type}' is classified as irreversible"
+
+    return False, "Action passed safety firewall inspection"
+
+
+def inspect_and_authorize(action_type: str, text: str = "", selector: str = "", force: bool = False) -> Dict[str, Any]:
+    """
+    Evaluates action and checks authorization policy.
+    Bypass is permitted only if force=True or ALLOW_DESTRUCTIVE=1 environment variable is set.
+    """
+    dangerous, reason = is_action_dangerous(action_type, text, selector)
+    bypass = force or os.environ.get("ALLOW_DESTRUCTIVE", "").lower() in ("true", "1", "yes")
+
+    result = {
+        "action": action_type,
+        "text": text,
+        "selector": selector,
+        "dangerous": dangerous,
+        "reason": reason,
+        "authorized": (not dangerous) or bypass,
+        "bypass_granted": bypass if dangerous else False
+    }
+    return result
+
+
+def inspect_code_snippet(code: str, force: bool = False) -> List[Dict[str, Any]]:
+    """
+    Parses a code snippet or script and checks all discovered UI interaction statements.
+    """
+    inspections = []
+    lines = code.splitlines()
+
+    for line_idx, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("//", "#", "/*", "*")):
+            continue
+
+        matched = False
+        for pattern in INTERACTION_CODE_PATTERNS:
+            for match in pattern.finditer(line):
+                matched = True
+                groups = match.groupdict()
+                act = groups.get("act") or "click"
+                sel = groups.get("sel") or ""
+                text = groups.get("text") or ""
+                auth = inspect_and_authorize(act, text=text, selector=sel, force=force)
+                auth["line"] = line_idx
+                auth["code"] = stripped
+                inspections.append(auth)
+
+        # Fallback: line itself contains dangerous keyword and an action verb
+        if not matched and COMPILED_TEXT_REGEX.search(stripped) and any(w in stripped.lower() for w in ("click", "press", "submit", "post", "delete")):
+            auth = inspect_and_authorize("dispatch", text=stripped, selector="", force=force)
+            auth["line"] = line_idx
+            auth["code"] = stripped
+            inspections.append(auth)
+
+    return inspections
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Action Safety Firewall & Blast Radius Containment Engine")
+    parser.add_argument("--action", default="click", help="Action type (click, fill, submit)")
+    parser.add_argument("--text", default="", help="Text content of target element")
+    parser.add_argument("--selector", default="", help="CSS/XPath selector of target element")
+    parser.add_argument("--code", default="", help="Direct code snippet or command line to evaluate (use '-' for stdin)")
+    parser.add_argument("--file", default="", help="Path to script file to evaluate")
+    parser.add_argument("--stdin", action="store_true", help="Read code or action from standard input")
+    parser.add_argument("--dry-run", action="store_true", help="Execute in pre-execution dry-run mode (outputs validation report)")
+    parser.add_argument("--force", action="store_true", help="Force bypass safety firewall")
+    parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+    args = parser.parse_args()
+
+    # Determine input source: explicit stdin flag/arg, --file, --code, or parameters
+    code_content = ""
+    if args.code and args.code != "-":
+        code_content = args.code
+    elif args.file and os.path.exists(args.file):
+        with open(args.file, "r", encoding="utf-8", errors="ignore") as f:
+            code_content = f.read()
+    elif args.stdin or args.code == "-":
+        try:
+            stdin_data = sys.stdin.read().strip()
+            if stdin_data:
+                # Check if stdin is JSON
+                if stdin_data.startswith("{") and stdin_data.endswith("}"):
+                    try:
+                        parsed = json.loads(stdin_data)
+                        if "action" in parsed or "selector" in parsed:
+                            args.action = parsed.get("action", args.action)
+                            args.text = parsed.get("text", args.text)
+                            args.selector = parsed.get("selector", args.selector)
+                        else:
+                            code_content = stdin_data
+                    except Exception:
+                        code_content = stdin_data
+                else:
+                    code_content = stdin_data
+        except Exception:
+            pass
+
+    # Evaluation
+    if code_content:
+        inspections = inspect_code_snippet(code_content, force=args.force)
+        has_blocked = any(not item["authorized"] for item in inspections)
+        all_authorized = not has_blocked
+
+        report = {
+            "mode": "dry-run" if args.dry_run else "enforce",
+            "total_inspected": len(inspections),
+            "authorized": all_authorized,
+            "blocked_count": sum(1 for item in inspections if not item["authorized"]),
+            "inspections": inspections
+        }
+
+        if args.json:
+            print(json.dumps(report, indent=2))
+        else:
+            tag = "DRY-RUN INSPECTION" if args.dry_run else "FIREWALL SENTINEL"
+            print(f"\n🛡️  [{tag}] Inspected {len(inspections)} interaction statements:")
+            for item in inspections:
+                status = "[PASS]" if item["authorized"] else "[BLOCKED]"
+                line_info = f"Line {item.get('line', '?')}: " if 'line' in item else ""
+                print(f"  {status} {line_info}{item['action']} -> {item['reason']}")
+                if not item["authorized"]:
+                    print(f"         Code: {item.get('code', '')}")
+
+            if all_authorized:
+                print(f"\n✅ All actions cleared by Safety Firewall{' (Dry-Run)' if args.dry_run else ''}.\n")
+            else:
+                print(f"\n❌ Pre-execution Blocked: Destructive actions intercepted without --force or ALLOW_DESTRUCTIVE=1.\n")
+
+        return 0 if all_authorized else 1
+
+    # Single-action check (legacy / parameter mode)
+    auth = inspect_and_authorize(args.action, args.text, args.selector, args.force)
+    auth["mode"] = "dry-run" if args.dry_run else "enforce"
+
+    if args.json:
+        print(json.dumps(auth, indent=2))
+    else:
+        prefix = "[DRY-RUN] " if args.dry_run else ""
+        if auth["authorized"]:
+            status_tag = f"{prefix}[PASS] Action Authorized" if not auth["dangerous"] else f"{prefix}[BYPASS] Destructive Action Force-Authorized"
+            print(f"🛡️  {status_tag}: {auth['reason']}")
+        else:
+            print(f"❌ {prefix}[BLOCKED] Action Safety Firewall Intercepted: {auth['reason']}")
+            print("   👉 To authorize, pass --force or set ALLOW_DESTRUCTIVE=1.")
+
+    return 0 if auth["authorized"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/setup_project.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+Enterprise QA Autonomous Project Setup & Bootstrap Engine
+----------------------------------------------------------
+Transforms any target test project into an AI-Ready Enterprise Suite in 1-click.
+Dispatched automatically by AI Agents (Zero-Command Protocol) or via 'agent-qa setup'.
+
+Automated actions:
+  1. Detects project tech stack (Katalon, Playwright, Cypress, Pytest).
+  2. Generates tailored 'PROJECT_AI_GUIDE.md' if missing.
+  3. Installs automated Git Pre-Push Hook (.git/hooks/pre-push) for zero-leakage protection.
+  4. Triggers 5-in-1 Health Audit (tools/analyze_project.py):
+     - Maps AST method signatures (repo_map.txt).
+     - Scans fake passes (infer_linter).
+     - Audits database teardown hygiene (trace_data_flow).
+     - Generates in-project health report (PROJECT_HEALTH_REPORT.md).
+"""
+
+import os
+import sys
+import shutil
+import argparse
+from pathlib import Path
+from datetime import datetime
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+TEMPLATES_DIR = os.path.join(HUB_ROOT, "templates")
+sys.path.insert(0, SCRIPT_DIR)
+
+import analyze_project
+import verify_all
+import project_state
+
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def resolve_target_repo(cli_target=None, cli_repo=None):
+    chosen = cli_repo or cli_target
+    if chosen:
+        resolved = os.path.abspath(chosen)
+        if not os.path.exists(resolved):
+            raise FileNotFoundError(f"Target repository path not found: {resolved}")
+        return resolved
+
+    env_dir = os.environ.get("TARGET_PROJECT_DIR")
+    if env_dir and os.path.exists(env_dir):
+        return os.path.abspath(env_dir)
+
+    cwd = os.path.abspath(os.getcwd())
+    if cwd.lower() != HUB_ROOT.lower():
+        return cwd
+
+    return HUB_ROOT
+
+
+def detect_tech_stack(target_dir):
+    """Detects target project automation framework and script language."""
+    target_path = Path(target_dir)
+
+    # 1. Katalon Studio check
+    prj_files = list(target_path.glob("*.prj"))
+    if prj_files or (target_path / "Keywords").is_dir() or (target_path / "Scripts").is_dir():
+        prj_name = prj_files[0].stem if prj_files else target_path.name
+        return {
+            "name": prj_name,
+            "framework": "Katalon Studio (Enterprise Web)",
+            "language": "Groovy",
+            "page_dir": "Keywords/pages",
+            "test_dir": "Scripts",
+            "run_cmd": "./tools/run_headless_kre.sh (or katalonc CLI)"
+        }
+
+    # 2. Playwright check
+    if (target_path / "playwright.config.ts").exists() or (target_path / "playwright.config.js").exists():
+        is_ts = (target_path / "playwright.config.ts").exists() or (target_path / "tsconfig.json").exists()
+        return {
+            "name": target_path.name,
+            "framework": "Playwright Test",
+            "language": "TypeScript" if is_ts else "JavaScript",
+            "page_dir": "src/pages" if (target_path / "src" / "pages").exists() else "pages",
+            "test_dir": "tests",
+            "run_cmd": "npx playwright test --project=chromium"
+        }
+
+    # 3. Cypress check
+    if (target_path / "cypress.config.ts").exists() or (target_path / "cypress.config.js").exists():
+        return {
+            "name": target_path.name,
+            "framework": "Cypress E2E",
+            "language": "TypeScript" if (target_path / "cypress.config.ts").exists() else "JavaScript",
+            "page_dir": "cypress/pages",
+            "test_dir": "cypress/e2e",
+            "run_cmd": "npx cypress run --headless"
+        }
+
+    # 4. Pytest check
+    if (target_path / "pytest.ini").exists() or list(target_path.glob("test_*.py")):
+        return {
+            "name": target_path.name,
+            "framework": "Pytest",
+            "language": "Python",
+            "page_dir": "pages",
+            "test_dir": "tests",
+            "run_cmd": "pytest tests/ -v"
+        }
+
+    # Default fallback
+    return {
+        "name": target_path.name,
+        "framework": "Enterprise Test Automation",
+        "language": "TypeScript / Groovy",
+        "page_dir": "pages",
+        "test_dir": "tests",
+        "run_cmd": "npm test"
+    }
+
+
+def ensure_project_ai_guide(target_dir, stack_info):
+    """Generates PROJECT_AI_GUIDE.md tailored to the target project if missing."""
+    guide_path = os.path.join(target_dir, "PROJECT_AI_GUIDE.md")
+    if os.path.exists(guide_path):
+        print(f"  [PASS] PROJECT_AI_GUIDE.md already exists: {guide_path}")
+        return False
+
+    template_path = os.path.join(TEMPLATES_DIR, "PROJECT_AI_GUIDE_TEMPLATE.md")
+    content = ""
+    if os.path.exists(template_path):
+        with open(template_path, "r", encoding="utf-8") as f:
+            content = f.read()
+    else:
+        content = f"# PROJECT AI GUIDE: {stack_info['name']}\n\n## 1. General System Under Test\n"
+
+    # Populate template placeholders with detected project metadata
+    content = content.replace("[TARGET_PROJECT_NAME]", stack_info["name"])
+    content = content.replace("[e.g., Enterprise Billing Platform / Customer Portal]", stack_info["name"])
+    content = content.replace("[e.g., Playwright Test, Katalon Studio 10.x, Cypress, Selenium]", stack_info["framework"])
+    content = content.replace("[e.g., TypeScript, Groovy, Python, JavaScript]", stack_info["language"])
+    content = content.replace("src/pages/... or Keywords/pages/...", stack_info["page_dir"])
+    content = content.replace("tests/e2e/... or Scripts/...", stack_info["test_dir"])
+    content = content.replace("[e.g., npx playwright test --project=chromium --reporter=html,junit:results.xml]", stack_info["run_cmd"])
+
+    with open(guide_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    print(f"  {GREEN}[OK] Generated PROJECT_AI_GUIDE.md tailored to {stack_info['framework']}:{RESET} {guide_path}")
+    return True
+
+
+def install_git_pre_push_hook(target_dir):
+    """Installs an automated pre-push hook into target project's .git repository."""
+    git_dir = os.path.join(target_dir, ".git")
+    if not os.path.isdir(git_dir):
+        print("  [SKIP] Not a Git repository root (.git folder not found). Skipped Git Hook installation.")
+        return False
+
+    hooks_dir = os.path.join(git_dir, "hooks")
+    os.makedirs(hooks_dir, exist_ok=True)
+    hook_file = os.path.join(hooks_dir, "pre-push")
+
+    verify_all_script = os.path.join(SCRIPT_DIR, "verify_all.py").replace("\\", "/")
+    analyze_script = os.path.join(SCRIPT_DIR, "analyze_project.py").replace("\\", "/")
+
+    hook_content = f"""#!/bin/sh
+# Automated Zero-Leakage Pre-Push Hook (Installed by Enterprise Agent-QA)
+# Automatically enforces 7 Quality Gates and syncs project health before pushing.
+
+echo "\\n[AI-GUARD] Running Pre-Push Verification (7 Quality Gates DoD)..."
+python3 "{verify_all_script}" || python "{verify_all_script}"
+if [ $? -ne 0 ]; then
+    echo "\\n[AI-GUARD - REJECTED] Git Push aborted: 7 Quality Gates verification failed!"
+    echo "Please fix defects or run 'agent-qa verify' locally before pushing.\\n"
+    exit 1
+fi
+
+echo "[AI-GUARD - PASSED] 7 Quality Gates satisfied. Syncing project health report..."
+python3 "{analyze_script}" || python "{analyze_script}"
+echo "[AI-GUARD - READY] Pushing to remote...\\n"
+exit 0
+"""
+    try:
+        with open(hook_file, "w", encoding="utf-8", newline="\n") as f:
+            f.write(hook_content)
+
+        # Attempt to make executable on Unix-like environments
+        try:
+            os.chmod(hook_file, 0o755)
+        except Exception:
+            pass
+
+        print(f"  {GREEN}[OK] Installed automated Pre-Push Git Hook:{RESET} {hook_file}")
+        return True
+    except Exception as e:
+        print(f"  ⚠️ Could not install Git hook: {e}")
+        return False
+
+
+def run_setup(target_repo):
+    """Main execution entrypoint for automated project setup."""
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}      AUTONOMOUS ZERO-COMMAND PROJECT BOOTSTRAP (AI-READY SETUP)     {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"📁 Target Project  : {target_repo}")
+
+    # 1. Detect Stack
+    stack_info = detect_tech_stack(target_repo)
+    print(f"🔍 Detected Stack  : {BOLD}{stack_info['framework']}{RESET} ({stack_info['language']})")
+    print(f"📂 Structure Scope : Pages: `{stack_info['page_dir']}` | Tests: `{stack_info['test_dir']}`\n")
+
+    # 2. Ensure PROJECT_AI_GUIDE.md & PROJECT_STATE.md
+    print(f"{BOLD}[1/3] Checking Project AI Guide & State Anchor...{RESET}")
+    guide_created = ensure_project_ai_guide(target_repo, stack_info)
+    project_state.init_state(target_repo)
+
+    # 3. Install Pre-Push Git Hook
+    print(f"\n{BOLD}[2/3] Installing Zero-Leakage Git Pre-Push Hook...{RESET}")
+    hook_installed = install_git_pre_push_hook(target_repo)
+
+    # 4. Run 5-in-1 Comprehensive Health & AST Analysis
+    print(f"\n{BOLD}[3/3] Executing Initial Health Audit & AST Mapping...{RESET}")
+    analysis_code = analyze_project.run_full_analysis(target_repo)
+
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}            🎉 PROJECT IS NOW 100% AI-READY (LEVEL 5 SETUP)           {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"  Target Framework    : {stack_info['framework']}")
+    print(f"  AI Project Guide    : {os.path.join(target_repo, 'PROJECT_AI_GUIDE.md')}")
+    print(f"  AST Method Map      : {os.path.join(target_repo, 'repo_map.txt')}")
+    print(f"  Health Report       : {os.path.join(target_repo, 'PROJECT_HEALTH_REPORT.md')}")
+    print(f"  Pre-Push Sentinel   : {'ACTIVE (.git/hooks/pre-push)' if hook_installed else 'MANUAL (No .git folder)'}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}\n")
+
+    return analysis_code
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Autonomous Enterprise QA Project Setup")
+    parser.add_argument("target", nargs="?", default=None, help="Target repository path to setup")
+    parser.add_argument("--repo", "--path", dest="repo_path", default=None, help="Target repository path")
+    args = parser.parse_args()
+
+    try:
+        target_repo = resolve_target_repo(cli_target=args.target, cli_repo=args.repo_path)
+    except FileNotFoundError as e:
+        print(f"❌ Error: {e}")
+        return 1
+
+    return run_setup(target_repo)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/smart_visual_masker.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Smart Visual Masker & Anti-Flake Visual Engine
+----------------------------------------------
+Eliminates 99% of false alarms in Visual Regression Testing.
+Automatically disables dynamic CSS animations, freezes SVG spinners,
+and masks fluctuating UI elements (timestamps, clocks, avatars, ad banners).
+"""
+
+import os
+import re
+import json
+import argparse
+from typing import List, Dict, Any, Tuple
+
+
+class SmartVisualMasker:
+    """Enterprise Visual Regression Anti-Flake & Dynamic Masking Engine."""
+
+    ANTI_FLAKE_CSS = """
+    *, *::before, *::after {
+        transition-property: none !important;
+        transform: none !important;
+        animation: none !important;
+        caret-color: transparent !important;
+        scroll-behavior: auto !important;
+    }
+    """
+
+    DEFAULT_MASK_SELECTORS = [
+        # Timestamps and dates
+        "time",
+        ".timestamp",
+        ".date-time",
+        ".clock",
+        "[data-testid*='date']",
+        "[data-testid*='time']",
+        "[class*='countdown']",
+        # Random avatars & dynamic user content
+        ".avatar",
+        "img.user-avatar",
+        "[data-testid*='avatar']",
+        # Ads and third-party widgets
+        ".ad-banner",
+        ".advertisement",
+        "iframe[id*='google']",
+        # Skeleton loaders & spinners
+        ".skeleton",
+        ".loading-placeholder",
+        ".spinner"
+    ]
+
+    @classmethod
+    def get_anti_flake_css(cls) -> str:
+        """Returns normalized CSS string to freeze all animations and transitions."""
+        return cls.ANTI_FLAKE_CSS.strip()
+
+    @classmethod
+    def generate_playwright_ts_options(cls, additional_selectors: List[str] = None) -> str:
+        """
+        Generates Playwright TypeScript assertion options with masking and disabled animations.
+        """
+        selectors = cls.DEFAULT_MASK_SELECTORS + (additional_selectors or [])
+        locators_ts = ",\n    ".join([f"page.locator('{sel}')" for sel in selectors])
+        
+        return f"""await expect(page).toHaveScreenshot('visual-baseline.png', {{
+  animations: 'disabled',
+  caret: 'hide',
+  scale: 'css',
+  maxDiffPixelRatio: 0.01,
+  mask: [
+    {locators_ts}
+  ]
+}});"""
+
+    @classmethod
+    def generate_browser_mask_script(cls, selectors: List[str] = None) -> str:
+        """
+        Generates JavaScript snippet to run inside the live browser
+        to immediately freeze DOM animations and paint solid black masks
+        over dynamic timestamp/avatar elements.
+        """
+        target_selectors = selectors or cls.DEFAULT_MASK_SELECTORS
+        selectors_json = json.dumps(target_selectors)
+        return f"""(() => {{
+    // 1. Inject anti-flake styles
+    const style = document.createElement('style');
+    style.innerHTML = `{cls.get_anti_flake_css()}`;
+    document.head.appendChild(style);
+
+    // 2. Solid mask for dynamic elements
+    const selectors = {selectors_json};
+    let maskedCount = 0;
+    selectors.forEach(sel => {{
+        document.querySelectorAll(sel).forEach(el => {{
+            el.style.backgroundColor = '#000000';
+            el.style.color = '#000000';
+            el.style.visibility = 'visible';
+            el.setAttribute('data-visual-masked', 'true');
+            maskedCount++;
+        }});
+    }});
+    return {{ status: 'OK', maskedCount }};
+}})();"""
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Smart Visual Masker & Anti-Flake Visual Engine")
+    parser.add_argument("--css", action="store_true", help="Print anti-flake CSS")
+    parser.add_argument("--js-script", action="store_true", help="Print browser in-page masking JavaScript")
+    parser.add_argument("--playwright-snippet", action="store_true", help="Generate Playwright TS visual assertion snippet")
+    parser.add_argument("--mask", action="append", default=[], help="Additional CSS selectors to mask")
+
+    args = parser.parse_args()
+
+    if args.css:
+        print(SmartVisualMasker.get_anti_flake_css())
+    elif args.js_script:
+        print(SmartVisualMasker.generate_browser_mask_script(args.mask or None))
+    elif args.playwright_snippet:
+        print(SmartVisualMasker.generate_playwright_ts_options(args.mask or None))
+    else:
+        print("======================================================================")
+        print("  SMART VISUAL MASKER & ANTI-FLAKE VISUAL ENGINE")
+        print("======================================================================")
+        print("Default Masked Selectors:")
+        for sel in SmartVisualMasker.DEFAULT_MASK_SELECTORS:
+            print(f"  • {sel}")
+        print("\nUse --css, --js-script, or --playwright-snippet for code output.")
+        print("======================================================================")
+
+
+if __name__ == "__main__":
+    main()