pi-ui-extend 1.0.41 → 1.0.45

package/external/pi-tools-suite/src/async-subagents/agents/ui-qa/drivers/windows/windows-uia.ps1

@@ -0,0 +1,454 @@
+$ErrorActionPreference = "Stop"
+$ProgressPreference = "SilentlyContinue"
+
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+Add-Type -AssemblyName System.Drawing
+
+Add-Type -TypeDefinition @'
+using System;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class UiQaWin32 {
+    [StructLayout(LayoutKind.Sequential)]
+    public struct RECT { public int Left, Top, Right, Bottom; }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct INPUT { public uint type; public InputUnion U; }
+
+    [StructLayout(LayoutKind.Explicit)]
+    struct InputUnion { [FieldOffset(0)] public KEYBDINPUT ki; }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct KEYBDINPUT {
+        public ushort wVk;
+        public ushort wScan;
+        public uint dwFlags;
+        public uint time;
+        public UIntPtr dwExtraInfo;
+    }
+
+    [DllImport("user32.dll", SetLastError=true)]
+    public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
+
+    [DllImport("user32.dll", SetLastError=true)]
+    public static extern bool PrintWindow(IntPtr hwnd, IntPtr hdcBlt, uint flags);
+
+    [DllImport("user32.dll")]
+    public static extern bool SetForegroundWindow(IntPtr hWnd);
+
+    [DllImport("user32.dll")]
+    public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+
+    [DllImport("user32.dll")]
+    static extern bool SetCursorPos(int x, int y);
+
+    [DllImport("user32.dll")]
+    static extern void mouse_event(uint flags, uint dx, uint dy, uint data, UIntPtr extra);
+
+    [DllImport("user32.dll", SetLastError=true)]
+    static extern uint SendInput(uint count, INPUT[] inputs, int size);
+
+    const uint INPUT_KEYBOARD = 1;
+    const uint KEYEVENTF_KEYUP = 0x0002;
+    const uint KEYEVENTF_UNICODE = 0x0004;
+    const uint MOUSEEVENTF_LEFTDOWN = 0x0002;
+    const uint MOUSEEVENTF_LEFTUP = 0x0004;
+
+    static INPUT Key(ushort vk, ushort scan, uint flags) {
+        var input = new INPUT();
+        input.type = INPUT_KEYBOARD;
+        input.U.ki.wVk = vk;
+        input.U.ki.wScan = scan;
+        input.U.ki.dwFlags = flags;
+        return input;
+    }
+
+    public static void SendUnicodeText(string text) {
+        foreach (char ch in text) {
+            var inputs = new [] {
+                Key(0, ch, KEYEVENTF_UNICODE),
+                Key(0, ch, KEYEVENTF_UNICODE | KEYEVENTF_KEYUP),
+            };
+            if (SendInput((uint)inputs.Length, inputs, Marshal.SizeOf(typeof(INPUT))) != (uint)inputs.Length)
+                throw new InvalidOperationException("SendInput failed while typing text");
+        }
+    }
+
+    public static void SendKeyChord(ushort key, ushort[] modifiers) {
+        var inputs = new System.Collections.Generic.List<INPUT>();
+        foreach (var modifier in modifiers) inputs.Add(Key(modifier, 0, 0));
+        inputs.Add(Key(key, 0, 0));
+        inputs.Add(Key(key, 0, KEYEVENTF_KEYUP));
+        for (int i = modifiers.Length - 1; i >= 0; i--) inputs.Add(Key(modifiers[i], 0, KEYEVENTF_KEYUP));
+        var value = inputs.ToArray();
+        if (SendInput((uint)value.Length, value, Marshal.SizeOf(typeof(INPUT))) != (uint)value.Length)
+            throw new InvalidOperationException("SendInput failed while sending key chord");
+    }
+
+    public static void ClickPoint(int x, int y) {
+        if (!SetCursorPos(x, y)) throw new InvalidOperationException("SetCursorPos failed");
+        mouse_event(MOUSEEVENTF_LEFTDOWN, 0, 0, 0, UIntPtr.Zero);
+        mouse_event(MOUSEEVENTF_LEFTUP, 0, 0, 0, UIntPtr.Zero);
+    }
+
+    public static void CaptureWindow(IntPtr hwnd, string file) {
+        RECT rect;
+        if (hwnd == IntPtr.Zero || !GetWindowRect(hwnd, out rect))
+            throw new InvalidOperationException("could not resolve target window rectangle");
+        int width = Math.Max(1, rect.Right - rect.Left);
+        int height = Math.Max(1, rect.Bottom - rect.Top);
+        using (var bitmap = new Bitmap(width, height, PixelFormat.Format32bppArgb)) {
+            using (var graphics = Graphics.FromImage(bitmap)) {
+                IntPtr hdc = graphics.GetHdc();
+                bool printed = false;
+                try { printed = PrintWindow(hwnd, hdc, 2); }
+                finally { graphics.ReleaseHdc(hdc); }
+                if (!printed) graphics.CopyFromScreen(rect.Left, rect.Top, 0, 0, new Size(width, height));
+            }
+            bitmap.Save(file, ImageFormat.Png);
+        }
+    }
+}
+'@
+
+function Fail([string]$Message) {
+    [Console]::Error.WriteLine($Message)
+    exit 1
+}
+
+function Parse-Options([string[]]$Values) {
+    $result = @{}
+    $index = 0
+    while ($index -lt $Values.Count) {
+        $key = $Values[$index]
+        if (-not $key.StartsWith("--")) { Fail "unexpected argument: $key" }
+        $name = $key.Substring(2)
+        if ($name -in @("all", "print-pid")) {
+            $result[$name] = $true
+            $index += 1
+            continue
+        }
+        if ($index + 1 -ge $Values.Count) { Fail "missing value for $key" }
+        if ($result.ContainsKey($name)) { Fail "duplicate option: $key" }
+        $result[$name] = $Values[$index + 1]
+        $index += 2
+    }
+    return $result
+}
+
+function Require-Option($Options, [string]$Name) {
+    if (-not $Options.ContainsKey($Name) -or [string]::IsNullOrWhiteSpace([string]$Options[$Name])) {
+        Fail "missing --$Name"
+    }
+    return [string]$Options[$Name]
+}
+
+function Control-Role([System.Windows.Automation.AutomationElement]$Element) {
+    $programmatic = $Element.Current.ControlType.ProgrammaticName
+    if ($programmatic -and $programmatic.Contains(".")) { return $programmatic.Split(".")[-1] }
+    return [string]$programmatic
+}
+
+function Scalar-String($Value) {
+    if ($null -eq $Value) { return $null }
+    if ($Value -is [bool]) { return $Value.ToString().ToLowerInvariant() }
+    return [string]$Value
+}
+
+function Element-Attributes([System.Windows.Automation.AutomationElement]$Element) {
+    $attributes = [ordered]@{}
+    if (-not [string]::IsNullOrEmpty($Element.Current.Name)) { $attributes.title = $Element.Current.Name }
+    if (-not [string]::IsNullOrEmpty($Element.Current.ItemStatus)) { $attributes.description = $Element.Current.ItemStatus }
+    if (-not [string]::IsNullOrEmpty($Element.Current.AutomationId)) { $attributes.identifier = $Element.Current.AutomationId }
+    if (-not [string]::IsNullOrEmpty($Element.Current.HelpText)) { $attributes.help = $Element.Current.HelpText }
+    if ($Element.Current.ControlType -eq [System.Windows.Automation.ControlType]::Edit -and $Element.Current.IsPassword) {
+        $attributes.value = "<redacted>"
+    } else {
+        $pattern = $null
+        if ($Element.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern)) {
+            $attributes.value = ([System.Windows.Automation.ValuePattern]$pattern).Current.Value
+        } else {
+            $toggle = $null
+            if ($Element.TryGetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern, [ref]$toggle)) {
+                $toggleState = ([System.Windows.Automation.TogglePattern]$toggle).Current.ToggleState
+                if ($toggleState -eq [System.Windows.Automation.ToggleState]::On) { $attributes.value = "1" }
+                elseif ($toggleState -eq [System.Windows.Automation.ToggleState]::Off) { $attributes.value = "0" }
+                else { $attributes.value = "mixed" }
+            }
+        }
+    }
+    $attributes.enabled = Scalar-String $Element.Current.IsEnabled
+    $attributes.focused = Scalar-String $Element.Current.HasKeyboardFocus
+    $selection = $null
+    if ($Element.TryGetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern, [ref]$selection)) {
+        $attributes.selected = Scalar-String ([System.Windows.Automation.SelectionItemPattern]$selection).Current.IsSelected
+    }
+    return $attributes
+}
+
+function Element-Record([System.Windows.Automation.AutomationElement]$Element, [string]$Path) {
+    $rect = $Element.Current.BoundingRectangle
+    return [ordered]@{
+        path = $Path
+        role = Control-Role $Element
+        attributes = Element-Attributes $Element
+        frame = [ordered]@{
+            x = [int][math]::Round($rect.X)
+            y = [int][math]::Round($rect.Y)
+            width = [int][math]::Round($rect.Width)
+            height = [int][math]::Round($rect.Height)
+        }
+    }
+}
+
+function Get-Children([System.Windows.Automation.AutomationElement]$Element) {
+    $result = New-Object System.Collections.Generic.List[System.Windows.Automation.AutomationElement]
+    $walker = [System.Windows.Automation.TreeWalker]::RawViewWalker
+    $child = $walker.GetFirstChild($Element)
+    while ($null -ne $child) {
+        $result.Add($child)
+        $child = $walker.GetNextSibling($child)
+    }
+    return $result
+}
+
+function Get-DescendantPids([int]$OwnerPid) {
+    $wanted = New-Object 'System.Collections.Generic.HashSet[int]'
+    [void]$wanted.Add($OwnerPid)
+    try {
+        $processes = @(Get-CimInstance Win32_Process -ErrorAction Stop | Select-Object ProcessId, ParentProcessId)
+        $changed = $true
+        while ($changed) {
+            $changed = $false
+            foreach ($process in $processes) {
+                if ($wanted.Contains([int]$process.ParentProcessId) -and -not $wanted.Contains([int]$process.ProcessId)) {
+                    [void]$wanted.Add([int]$process.ProcessId)
+                    $changed = $true
+                }
+            }
+        }
+    } catch {
+        # Exact owner PID remains a safe fallback if WMI/CIM is unavailable.
+    }
+    return ,$wanted
+}
+
+function Find-AppWindow($Options) {
+    $roots = [System.Windows.Automation.AutomationElement]::RootElement.FindAll(
+        [System.Windows.Automation.TreeScope]::Children,
+        [System.Windows.Automation.Condition]::TrueCondition
+    )
+    $matches = New-Object System.Collections.Generic.List[System.Windows.Automation.AutomationElement]
+    $pids = $null
+    if ($Options.ContainsKey("pid")) {
+        $pids = New-Object 'System.Collections.Generic.HashSet[int]'
+        [void]$pids.Add([int](Require-Option $Options "pid"))
+    } elseif ($Options.ContainsKey("owner-pid")) {
+        $pids = Get-DescendantPids ([int](Require-Option $Options "owner-pid"))
+    }
+    $name = if ($Options.ContainsKey("app")) { [string]$Options.app } else { $null }
+    $title = if ($Options.ContainsKey("title")) { [string]$Options.title } else { $null }
+    foreach ($root in $roots) {
+        if ($pids -and -not $pids.Contains([int]$root.Current.ProcessId)) { continue }
+        if ($title -and $root.Current.Name.IndexOf($title, [StringComparison]::OrdinalIgnoreCase) -lt 0) { continue }
+        if ($name) {
+            $processName = ""
+            try { $processName = (Get-Process -Id $root.Current.ProcessId -ErrorAction Stop).ProcessName } catch {}
+            if ($root.Current.Name.IndexOf($name, [StringComparison]::OrdinalIgnoreCase) -lt 0 -and
+                $processName.IndexOf($name, [StringComparison]::OrdinalIgnoreCase) -lt 0) { continue }
+        }
+        $matches.Add($root)
+    }
+    if ($matches.Count -eq 0) { return $null }
+    if ($matches.Count -gt 1 -and -not $pids -and -not $title) { Fail "ambiguous app selector ($($matches.Count) windows); use --pid" }
+    return $matches[0]
+}
+
+function Wait-AppWindow($Options, [double]$TimeoutSeconds) {
+    $deadline = [DateTime]::UtcNow.AddSeconds($TimeoutSeconds)
+    while ([DateTime]::UtcNow -lt $deadline) {
+        $window = Find-AppWindow $Options
+        if ($null -ne $window) { return $window }
+        Start-Sleep -Milliseconds 100
+    }
+    Fail "timed out waiting for application window"
+}
+
+function Focus-Window([System.Windows.Automation.AutomationElement]$Window) {
+    $handle = [IntPtr]$Window.Current.NativeWindowHandle
+    if ($handle -ne [IntPtr]::Zero) {
+        [void][UiQaWin32]::ShowWindow($handle, 9)
+        [void][UiQaWin32]::SetForegroundWindow($handle)
+    }
+    try { $Window.SetFocus() } catch {}
+}
+
+function Walk-Tree([System.Windows.Automation.AutomationElement]$Root, [int]$Depth, [int]$Limit) {
+    $records = New-Object System.Collections.Generic.List[object]
+    function Visit($Element, [string]$Path, [int]$Level) {
+        if ($records.Count -ge $Limit) { return }
+        $records.Add((Element-Record $Element $Path))
+        if ($Level -ge $Depth) { return }
+        $children = @(Get-Children $Element)
+        for ($index = 0; $index -lt $children.Count; $index++) {
+            Visit $children[$index] "$Path/$index" ($Level + 1)
+            if ($records.Count -ge $Limit) { return }
+        }
+    }
+    Visit $Root "0" 0
+    return $records
+}
+
+function Find-Element([System.Windows.Automation.AutomationElement]$Window, $Options) {
+    if ($Options.ContainsKey("path")) {
+        $parts = ([string]$Options.path).Split('/') | Where-Object { $_ -ne "" }
+        $current = $Window
+        $start = if ($parts.Count -gt 0 -and $parts[0] -eq "0") { 1 } else { 0 }
+        for ($index = $start; $index -lt $parts.Count; $index++) {
+            $childIndex = 0
+            if (-not [int]::TryParse($parts[$index], [ref]$childIndex)) { Fail "invalid element path" }
+            $children = @(Get-Children $current)
+            if ($childIndex -lt 0 -or $childIndex -ge $children.Count) { Fail "element path does not exist" }
+            $current = $children[$childIndex]
+        }
+        return $current
+    }
+    $match = Require-Option $Options "match"
+    $role = if ($Options.ContainsKey("role")) { ([string]$Options.role).Replace("AX", "").Replace(" ", "") } else { $null }
+    $occurrence = if ($Options.ContainsKey("occurrence")) { [int]$Options.occurrence } else { 1 }
+    $seen = 0
+    foreach ($record in (Walk-Tree $Window 20 1000)) {
+        $path = [string]$record.path
+        $element = Find-Element $Window @{ path = $path }
+        $attributes = Element-Attributes $element
+        $text = @($attributes.title, $attributes.description, $attributes.identifier, $attributes.help, $attributes.value) -join " "
+        if ($text.IndexOf($match, [StringComparison]::OrdinalIgnoreCase) -lt 0) { continue }
+        if ($role -and (Control-Role $element).Replace(" ", "") -ne $role) { continue }
+        $seen += 1
+        if ($seen -eq $occurrence) { return $element }
+    }
+    Fail "no accessibility element matches the supplied selector"
+}
+
+function Format-InspectRecord($Record) {
+    $parts = New-Object System.Collections.Generic.List[string]
+    $parts.Add([string]$Record.path)
+    $parts.Add([string]$Record.role)
+    foreach ($entry in $Record.attributes.GetEnumerator()) {
+        if ($null -eq $entry.Value -or [string]::IsNullOrEmpty([string]$entry.Value)) { continue }
+        $safe = ([string]$entry.Value).Replace("`r", " ").Replace("`n", " ").Replace([string][char]34, ('\' + [char]34))
+        $parts.Add("$($entry.Key)=`"$safe`"")
+    }
+    $frame = $Record.frame
+    $parts.Add("frame=$($frame.x),$($frame.y),$($frame.width)x$($frame.height)")
+    return $parts -join " "
+}
+
+function Invoke-Element([System.Windows.Automation.AutomationElement]$Element) {
+    $pattern = $null
+    if ($Element.TryGetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern, [ref]$pattern)) {
+        ([System.Windows.Automation.InvokePattern]$pattern).Invoke(); return
+    }
+    if ($Element.TryGetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern, [ref]$pattern)) {
+        ([System.Windows.Automation.SelectionItemPattern]$pattern).Select(); return
+    }
+    if ($Element.TryGetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern, [ref]$pattern)) {
+        ([System.Windows.Automation.TogglePattern]$pattern).Toggle(); return
+    }
+    $rect = $Element.Current.BoundingRectangle
+    if ($rect.Width -le 0 -or $rect.Height -le 0) { Fail "element has no actionable accessibility pattern or visible frame" }
+    [UiQaWin32]::ClickPoint([int]($rect.X + $rect.Width / 2), [int]($rect.Y + $rect.Height / 2))
+}
+
+function Key-Code([string]$Name) {
+    $map = @{
+        "enter"=0x0D; "return"=0x0D; "escape"=0x1B; "esc"=0x1B; "tab"=0x09; "backspace"=0x08;
+        "delete"=0x2E; "left"=0x25; "up"=0x26; "right"=0x27; "down"=0x28; "home"=0x24; "end"=0x23;
+        "pageup"=0x21; "pagedown"=0x22; "space"=0x20
+    }
+    $lower = $Name.ToLowerInvariant()
+    if ($map.ContainsKey($lower)) { return [ushort]$map[$lower] }
+    if ($Name.Length -eq 1) { return [ushort][char]$Name.ToUpperInvariant() }
+    Fail "unsupported key: $Name"
+}
+
+function Modifier-Codes([string]$Value) {
+    $result = New-Object System.Collections.Generic.List[ushort]
+    if ([string]::IsNullOrWhiteSpace($Value)) { return $result.ToArray() }
+    foreach ($raw in $Value.Split(',')) {
+        switch ($raw.Trim().ToLowerInvariant()) {
+            "cmd" { $result.Add([ushort]0x5B) }
+            "shift" { $result.Add([ushort]0x10) }
+            "ctrl" { $result.Add([ushort]0x11) }
+            "opt" { $result.Add([ushort]0x12) }
+            "alt" { $result.Add([ushort]0x12) }
+            "fn" { Fail "fn modifier is not supported by the Windows UI Automation helper" }
+            default { Fail "unsupported modifier: $raw" }
+        }
+    }
+    return $result.ToArray()
+}
+
+if ($args.Count -lt 1) { Fail "missing command" }
+$command = [string]$args[0]
+$options = Parse-Options @($args | Select-Object -Skip 1)
+
+if ($command -eq "doctor") {
+    try {
+        [void][System.Windows.Automation.AutomationElement]::RootElement
+        Write-Output "uia=available"
+        Write-Output "screenshot=available"
+        exit 0
+    } catch {
+        Fail "Windows UI Automation is unavailable: $($_.Exception.Message)"
+    }
+}
+
+$timeout = if ($options.ContainsKey("timeout")) { [double]$options.timeout } else { 15.0 }
+$window = Wait-AppWindow $options $timeout
+
+switch ($command) {
+    "wait-window" {
+        if ($options.ContainsKey("print-pid")) { Write-Output $window.Current.ProcessId }
+    }
+    "focus" { Focus-Window $window }
+    "inspect" {
+        $depth = if ($options.ContainsKey("depth")) { [int]$options.depth } else { 10 }
+        $limit = if ($options.ContainsKey("limit")) { [int]$options.limit } else { 80 }
+        foreach ($record in (Walk-Tree $window $depth $limit)) { Write-Output (Format-InspectRecord $record) }
+    }
+    "describe" {
+        $element = Find-Element $window $options
+        $pathValue = if ($options.ContainsKey("path")) { [string]$options.path } else { "match" }
+        (Element-Record $element $pathValue) | ConvertTo-Json -Compress -Depth 5
+    }
+    "screenshot" {
+        $out = Require-Option $options "out"
+        $directory = [IO.Path]::GetDirectoryName([IO.Path]::GetFullPath($out))
+        if (-not [IO.Directory]::Exists($directory)) { Fail "screenshot output directory does not exist" }
+        Focus-Window $window
+        [UiQaWin32]::CaptureWindow([IntPtr]$window.Current.NativeWindowHandle, $out)
+    }
+    "click" { Invoke-Element (Find-Element $window $options) }
+    "set-value" {
+        $element = Find-Element $window $options
+        $value = Require-Option $options "value"
+        $pattern = $null
+        if (-not $element.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern)) { Fail "element does not support ValuePattern" }
+        ([System.Windows.Automation.ValuePattern]$pattern).SetValue($value)
+    }
+    "type" {
+        Focus-Window $window
+        [UiQaWin32]::SendUnicodeText((Require-Option $options "text"))
+    }
+    "key" {
+        Focus-Window $window
+        $mods = if ($options.ContainsKey("modifiers")) { [ushort[]]@(Modifier-Codes ([string]$options.modifiers)) } else { [ushort[]]@() }
+        [UiQaWin32]::SendKeyChord((Key-Code (Require-Option $options "key")), $mods)
+    }
+    default { Fail "unsupported command: $command" }
+}

package/external/pi-tools-suite/src/async-subagents/agents/ui-qa/guides/browser-auth.md

@@ -0,0 +1,114 @@
+# Browser auth guide
+
+Load this guide only when a browser task actually requires authentication:
+profile discovery, form-auth scaffolding, or an auth update flow. Public QA
+needs no credentials and must not create `.pi/qa_auth.jsonc`.
+
+`PI_BROWSER_QA_RUNNER` names the installed trusted browser backend. Invoke it
+directly only for the commands in this guide; all probe/run browser execution
+still goes through `node "$PI_UI_QA_RUNNER"`.
+
+Never read, print, grep, copy, or edit credential values from
+`.pi/qa_auth.jsonc` yourself.
+
+## Profile discovery
+
+When a task requires authenticated behavior, first run:
+
+```sh
+node "$PI_BROWSER_QA_RUNNER" profiles
+```
+
+A missing auth config returns an empty list without creating
+`.pi/qa_auth.jsonc`. Choose an auth profile only when the task names its id,
+safe profile traits make the choice unambiguous, or a public run proves that
+the requested page requires login. Profiles live in project-local
+`.pi/qa_auth.jsonc` (mode `0600` on POSIX) and every profile declares its own
+exact `allowedOrigins`; listing output exposes only profile ids, descriptions,
+and traits.
+
+When an explicit authenticated request finds no usable profile, run:
+
+```sh
+node "$PI_BROWSER_QA_RUNNER" profiles --require-auth
+```
+
+Only `auth scaffold` and `profiles --require-auth` may create the private auth
+file.
+
+## Form-auth scaffolding
+
+When a public HTTPS login page (or loopback HTTP page for local development) is
+known and there is no usable profile, invoke the trusted runner once:
+
+```sh
+node "$PI_BROWSER_QA_RUNNER" auth scaffold \
+  --profile <safe-id> \
+  --login-url <public-login-url>
+```
+
+The runner discovers the login form and privately writes a target-specific
+`.pi/qa_auth.jsonc` containing `__PI_QA_SECRET_n__` values. It may create the
+file or replace only the runner's own empty generated template; it refuses to
+overwrite invalid or non-empty auth configuration. Never inspect the result.
+Relay `QA_AUTH_SCAFFOLD_CREATED`, the reported file, profile, placeholder count,
+and action, then ask the user to replace only those placeholder values. Browser
+QA must resume in a new run after the user confirms that edit.
+
+By default, login succeeds when the discovered form becomes hidden. A form-less
+page therefore requires an explicit deterministic signal using either
+`--success-url <glob>` or `--success-selector <selector>` with optional
+`--success-state attached|detached|visible|hidden`. Use `--base-url <url>` only
+to override the profile's same-origin application root. These are public
+metadata; never put credential values in command arguments or environment
+variables.
+
+Do not scaffold cookie, bearer, storage, storage-state, MFA, CAPTCHA, or
+federated login. For those modes, use the generic empty-template flow below and
+ask the user to configure the profile themselves.
+
+Do not request credentials merely because `.pi/qa_auth.jsonc` is absent. If the
+task explicitly requires authenticated behavior, or a public run reaches the
+flow's `authRejectedIf` check, and `profiles` returned no usable profile, run
+form-auth scaffolding when supported. Otherwise run
+`node "$PI_BROWSER_QA_RUNNER" profiles --require-auth`. Only these paths
+may create the private auth file.
+
+## Scaffold safety and edge cases
+
+The trusted runner discovers the most likely form, fillable fields, submit
+control, and form container on the unauthenticated page. It writes only
+discovered selectors and generated placeholders to the private `0600` config.
+The agent treats that config as opaque and user-owned. Scaffold status exposes
+only the file path, profile id, counts, and action, never inspected DOM text,
+input values, URLs, or selectors.
+
+Scaffolding rejects pages without a discoverable fillable field or submit
+control, form-less pages without an explicit success condition, remote HTTP
+login pages, cross-origin base URLs, malformed success options, symlinked or
+permissive auth paths, and invalid or non-empty existing configuration. Report
+these blockers; do not bypass them. No generated profile is usable until the
+user replaces its secret placeholders.
+
+## Blocked auth runs
+
+If a scaffold/profile command or an authenticated run returns
+`QA_AUTH_UPDATE_REQUIRED`, stop and explicitly report that authenticated
+browser QA requires credentials or an auth-config update. Ask the user to fill
+the reported file and rerun QA. If `templateCreated` is true, say that a
+private empty template was created at that path. Relay only the runner's
+profile, file, reason, action, and template-created state; never read the
+generated file or attempt to recover by exposing or replaying credentials. If
+the action is `fill_credentials`, also relay the placeholder count and tell the
+user to replace only the generated placeholder values.
+
+For any other blocked run, report the runner status and redacted reason. Do not
+claim that browser QA passed based on source inspection, unit tests, or a
+build.
+
+After any runner invocation that actually performed browser testing, include
+all non-empty `artifacts.screenshots`, `artifacts.videos`, and
+`artifacts.traces`, and `artifacts.downloads` groups in the final response.
+These links are mandatory so the user can open the evidence directly. Also
+include `visualInspection` with `inspected` or `unavailable`; never infer a
+visual pass from a successful runner status alone.

package/external/pi-tools-suite/src/async-subagents/agents/ui-qa/guides/browser-chrome-devtools.md

@@ -0,0 +1,91 @@
+# Browser detail: Chrome DevTools
+
+Load this topic only when the browser router or `selection.guide` selected
+`chrome-devtools`. Probe/run still goes through `PI_UI_QA_RUNNER`; never invoke
+`chrome-devtools` directly from the QA child.
+
+## Runner-owned security boundary
+
+The provider requires a compatible `chrome-devtools-mcp` CLI. The runner owns a
+random per-run daemon session and stops only that session. It starts an isolated
+Chrome/profile by default and applies fail-closed defaults: JavaScript
+evaluation and optional extension/PWA/experimental categories are disabled,
+usage statistics and CrUX lookup are disabled, network headers are redacted,
+writes are restricted to the run evidence directory, page-id routing is
+enabled, and exact target/allowed origins become the network allowlist.
+
+If the CLI/runtime is missing or too old, relay the runner's `BLOCKED` handoff;
+do not install or upgrade it from this child.
+
+## Target options
+
+Use `target.browserDriver: "chrome-devtools"` when explicit routing is needed.
+`target.profile` is not accepted: trusted QA authentication belongs to the
+Playwright route and credentials must never be moved into DevTools arguments,
+profiles, environment, or JavaScript.
+
+Optional `target.devtools` fields:
+
+- `headless`: boolean for runner-owned isolated Chrome, default `true`;
+- `browserUrl`: exact credential-free loopback HTTP endpoint for an already
+  debug-enabled Chrome; remote/non-loopback endpoints are rejected;
+- `reuseExistingBrowserSession`: boolean, valid only with `browserUrl`, and only
+  when the parent/user explicitly requires the existing authenticated session.
+
+Even when attached, the default is a task-owned isolated page/context. The
+runner closes only its created page and private daemon; it never stops external
+Chrome or closes unrelated tabs.
+
+Top-level deterministic `environment` is intentionally unsupported on this
+route. Split diagnostics into a separate flow instead of approximating the
+Playwright locale/timezone/motion contract.
+
+## DevTools flow surface
+
+Common actions supported here:
+
+- navigation/stability: `goto`, `reload`, `waitFor`, `waitForTimeout`;
+- interaction: `click`, `doubleClick`, `hover`, `fill`, `press`;
+- assertions: `assertVisible`, `assertText`, `assertURL`;
+- evidence: `screenshot`.
+
+DevTools-specific actions:
+
+- `snapshotAccessibility`: retain a structured accessibility-tree JSON;
+- `assertNoConsoleErrors`: require zero console errors;
+- `assertConsole`: match exactly one of `equals`/`includes`, optional `type`;
+- `assertNetworkRequest`: exact origin-relative `path`, uppercase `method`,
+  numeric `status`; optional `origin` must already be allowlisted;
+- `lighthouse`: sanitized summary, mode `navigation` or `snapshot`, optional
+  `desktop`/`mobile` device;
+- `performanceTrace`: temporary Chrome trace -> bounded numeric/insight summary
+  -> raw trace deletion;
+- `heapSummary`: temporary heapsnapshot -> sanitized numeric summary -> raw
+  snapshot close/deletion.
+
+Locators are deliberately narrow: `{role,name?,exact?}` or `{text,exact?}`.
+Each locator resolves against the latest accessibility snapshot to one unique
+UID; missing or ambiguous matches fail. If the requested scenario needs richer
+locators, frames/popups, trusted profiles, downloads, or actions absent above,
+use the Playwright route rather than weakening the test.
+
+## Oracles, privacy, and evidence
+
+Assertions remain the pass/fail oracle. Console/network checks publish only the
+bounded matcher result needed for QA; raw network headers and response bodies
+are not evidence. Never place secrets in expected console text, paths, or
+origins.
+
+Retained DevTools evidence may include explicit PNGs, accessibility snapshots,
+sanitized Lighthouse summaries, sanitized performance summaries, and sanitized
+heap summaries. Raw performance traces can contain URLs/query strings/network
+and call-frame details, so they are temporary. Raw heapsnapshots are temporary
+as well. Neither raw form is retained by the runner.
+
+This route does not currently promise automatic browser video, downloads, or a
+Playwright trace. Missing evidence types are capability differences, not a
+reason to synthesize evidence from another surface.
+
+Inspect representative screenshots before visual claims. Let the runner own
+the page/context, daemon, evidence, and cleanup; never issue provider-level
+start/stop or tab cleanup commands yourself.