pi-ui-extend 1.0.41 → 1.0.45

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

@@ -0,0 +1,145 @@
+# Browser detail: Playwright
+
+Load this topic only when the browser router or `selection.guide` selected
+`playwright`. Browser probe/run still goes through `PI_UI_QA_RUNNER`; do not
+invoke the bundled browser runner directly except for the explicit auth
+metadata/scaffold commands documented by the `auth` guide.
+
+## Target and authentication
+
+Use `target.browserDriver: "playwright"` when the route must be explicit.
+Supported target fields are `url`/`baseUrl`, exact `allowedOrigins`, optional
+trusted `profile`, and `browserDriver`. Do not combine Playwright with
+`target.devtools`.
+
+If the requested verification requires authentication, first load:
+
+```sh
+node "$PI_UI_QA_RUNNER" guide --backend browser --topic auth
+```
+
+Follow that guide for profile discovery/scaffolding. Never read, print, grep,
+copy, or edit credential values from `.pi/qa_auth.jsonc`; the trusted runner
+applies them internally. Put `authRejectedIf` directly after navigation or a
+transition that may expose an expired session.
+
+## Playwright flow surface
+
+Supported actions:
+
+- navigation/stability: `goto`, `reload`, `waitFor`, `waitForTimeout`;
+- interaction: `click`, `doubleClick`, `hover`, `fill`, `press`, `check`,
+  `uncheck`, `selectOption`, `wheel`, safe `evaluate`, `dragTo`, `uploadFiles`,
+  `openPopup`, `download`;
+- assertions: `assertVisible`, `assertHidden`, `assertEnabled`,
+  `assertDisabled`, `assertChecked`, `assertUnchecked`, `assertText`,
+  `assertTextContent`, `assertValue`, `assertAttribute`, `assertCount`,
+  `assertURL`, `assertDOMMetric`;
+- evidence/auth: `screenshot`, `authRejectedIf`.
+
+Locators accept exactly one primary selector from `testId`, `role` (optional
+`name`), `label`, `placeholder`, `text`, or `css`; add `exact: true` when useful.
+Prefer stable product contracts in that order, with CSS as a last resort.
+String assertions require exactly one of `equals` or `includes`.
+
+`assertText` uses visible rendered text; use `assertTextContent` only when raw
+DOM text is intentionally the oracle. `assertAttribute` is appropriate for
+observable `aria-*`, `data-*`, `href`, and similar state. Assertions retry
+within the bounded flow timeout.
+
+## Viewport and deterministic environment
+
+Optional top-level `viewport` accepts integer `width`/`height` from `320×240`
+through `3840×2160`; default is `1280×720`. The same dimensions drive recorded
+video.
+
+Optional top-level `environment` supports:
+
+- `locale`;
+- `timezoneId`;
+- `colorScheme`: `light`, `dark`, or `no-preference`;
+- `reducedMotion`: `reduce` or `no-preference`.
+
+Defaults are deterministic: `en-US`, `UTC`, `light`, and `reduce`. Set these
+explicitly when locale/timezone/theme/motion affects the behavior.
+
+## Interaction and causal expectations
+
+Visible interactions wait for document readiness, causally-started requests in
+a bounded readiness window, common visible busy markers, and a short stable
+recording interval. Prefer an assertion immediately after an action over an
+arbitrary sleep. `waitForTimeout` is bounded and should be exceptional.
+
+Triggering interactions may arm race-free expectations before input:
+
+- `expectResponse`: exact origin-relative `path`, uppercase `method`, and
+  integer `status` 100..599;
+- `expectDialog`: dialog `type`, a nested `message` matcher using exactly one of
+  `equals`/`includes`, and boolean `accept`.
+
+The runner does not publish response bodies/headers/query URLs or actual dialog
+text in diagnostics.
+
+`dragTo` requires a source `locator` and `dropTarget`, with optional bounded
+relative source/drop positions. Do not emulate unsupported drag protocols with
+raw JavaScript.
+
+`uploadFiles` is memory-only: entries are `{name,mimeType,base64}`, up to 10
+files, 5 MiB each and 10 MiB total. Filesystem paths/directories are unsupported;
+an empty list clears the file input.
+
+`download` atomically clicks and validates a nested safe filename matcher.
+`maxBytes` defaults to 5 MiB and is capped at 25 MiB. Retain bytes only when
+needed as evidence; retained downloads use runner-generated private names and
+are scanned for configured authentication before publication.
+
+## Frames, popups, scrolling, and safe evaluate
+
+`openPopup` captures a same-origin popup under a safe name (maximum three).
+Later steps can target `{ "type": "popup", "name": "..." }`. Same-origin
+iframes use `{ "type": "frame", "locator": {...} }`, optionally inside a named
+popup. Live origin is checked before scoped steps; cross-origin frames/popups
+are rejected unless the provider contract explicitly supports them.
+
+`wheel` accepts finite `deltaX`/`deltaY`, at least one non-zero. With a locator,
+the runner hovers it before wheel input.
+
+The `evaluate` action is not arbitrary JavaScript. Safe operations are:
+
+- `scrollTo`: optional locator plus numeric `x`/`y` or `"max"`;
+- `scrollBy`: optional locator plus numeric `deltaX`/`deltaY`;
+- `metrics`: optional locator and safe name, returning bounded layout metrics.
+
+Page/element metrics include scroll/client dimensions and positions. Use
+`assertDOMMetric` with exactly one comparator (`equals`, `greaterThan`,
+`greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`) for pass/fail.
+
+## Scenario design
+
+Build the proof as setup -> smallest user action -> observable oracle. For a
+fix verification, prefer one focused regression scenario rather than a tour.
+Use semantic locators and state transitions; do not add timeouts merely to hide
+races. A locator/setup error may justify fixing the flow, but an observed
+product mismatch must remain a failure.
+
+For responsive bugs, set the viewport and use DOM metrics when dimensions or
+scroll state are part of the proof. For custom loaders not covered by the
+runner's generic readiness model, explicitly wait/assert that loader state and
+then assert loaded content.
+
+## Evidence and cleanup
+
+The trusted Playwright backend attempts final/failure screenshot, first-page
+video, and sanitized post-auth trace; named `screenshot` steps should capture
+only materially useful states. Popups can add separate videos. Pointer actions
+may receive runner-owned visual annotations for chronology; those annotations
+are evidence, never the oracle.
+
+For authenticated form flows, password fields remain masked in video, but
+visible login identifiers may appear; treat evidence as private. Tracing begins
+only after login succeeds.
+
+Each invocation owns an isolated context and private evidence directory and
+closes resources in cleanup. Use separate runs for separate auth profiles. Do
+not create a shared browser context, expose storage/cookies to the model, or
+move backend evidence out of the agent-local workspace.

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

@@ -0,0 +1,82 @@
+# Browser backend router
+
+Load this guide only after the common UI-QA role classified the requested
+surface as `browser`. Use only the unified `PI_UI_QA_RUNNER` for probe/run.
+Provider-specific tools are runner implementation details and must not be
+invoked directly by the QA child.
+
+## Choose one detail route
+
+Choose from the requested proof, never from a repository/app name:
+
+- ordinary repeatable browser E2E, rich semantic/form locators, deterministic
+  browser environment, downloads, frames/popups, automatic video/trace, or
+  trusted QA authentication -> `playwright`;
+- browser-runtime diagnostics such as accessibility-tree snapshots,
+  console/network assertions, Lighthouse, performance summaries, or memory
+  summaries -> `chrome-devtools`;
+- authentication setup/update work -> load `auth` first, then use the
+  `playwright` detail guide for the verification flow.
+
+Load only the needed topic:
+
+```sh
+node "$PI_UI_QA_RUNNER" guide --backend browser --topic playwright
+node "$PI_UI_QA_RUNNER" guide --backend browser --topic chrome-devtools
+node "$PI_UI_QA_RUNNER" guide --backend browser --topic auth
+```
+
+`target.browserDriver` accepts `"auto"`, `"playwright"`, or
+`"chrome-devtools"`. Use `auto` when the flow itself makes the required
+capability unambiguous. When you must load a detail guide before authoring its
+provider-specific steps, explicitly set the matching driver for preflight.
+`target.profile` is a trusted-auth input and therefore routes to Playwright.
+
+After every completed-flow `probe`, `selection.guide` is authoritative. It must
+be `{ "backend": "browser", "topic": <the detail guide you are following> }`
+before `run`. If it differs, load that returned topic, fix the flow if needed,
+and probe again. Never weaken the requested proof merely to fit another
+provider.
+
+## Common browser flow
+
+The unified flow is declarative JSONC under
+`$PI_SUBAGENT_AGENT_DIR/ui-qa/flows/`:
+
+```jsonc
+{
+  "version": 1,
+  "target": {
+    "url": "https://example.test/",
+    "browserDriver": "auto"
+  },
+  "steps": []
+}
+```
+
+The target may use `url`/`baseUrl`, exact `allowedOrigins`, the selected
+`browserDriver`, and provider-specific fields documented by the loaded detail
+guide. Never put credentials, tokens, raw executable JavaScript, wildcard
+origins, or inferred sibling domains in a flow. A profile id and target URL are
+non-secret; credential values remain runner-owned.
+
+Treat discovery as a short preflight. Identify the real requested URL, the
+smallest user action that exercises the behavior, and a deterministic
+product-visible postcondition. A successful click/navigation is not proof.
+Verification uses one `run` per requested profile/variant; explicitly
+exploratory QA may use at most three bounded runs with one hypothesis each.
+
+Prefer state-based waits/assertions over sleeps. Preserve a product mismatch as
+a failure rather than changing the oracle. Additional origins must be exact
+`http(s)` origins explicitly justified by the requested scenario.
+
+## Evidence and reporting
+
+Report every artifact returned by the unified runner, including failed runs.
+Inspect at least one meaningful screenshot with `read` before claiming visual
+QA. Deterministic assertions determine PASS/FAIL; screenshots/video/traces
+explain the result.
+
+Let the runner own browser contexts/pages, provider processes, private evidence
+directories, and cleanup. Do not create shared/default browser sessions outside
+the runner or copy private QA evidence into a persistent shared directory.

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

@@ -0,0 +1,26 @@
+# Desktop detail: Linux AT-SPI
+
+Load this topic only when `selection.guide.topic` is `linux-at-spi`.
+
+The trusted bundled Python helper uses AT-SPI for semantic discovery,
+activation, values, text, and state assertions. Runtime availability depends on
+the graphical accessibility bus plus compatible `pyatspi` bindings. The QA
+child must not install bindings or start/replace the user's desktop bus.
+
+`target.application` may use `pid`, `name`, or a bounded runner-owned `launch`
+contract. `bundleId` is not a Linux identity. POSIX launch contracts stay in an
+owned detached process group so package-manager wrappers can hand off to a GUI
+descendant without escaping scoped cleanup.
+
+Keyboard input is advertised only when the runtime-probed `xdotool` producer is
+usable. Exact-window PNG evidence is advertised only when the helper can use a
+supported screenshot producer such as `gnome-screenshot` or `scrot`. Window
+video is currently unavailable and remains an explicit missing capability.
+
+Use the common desktop semantic actions/selectors and prefer AT-SPI
+role/name/state as the oracle. If accessibility bus, bindings, keyboard, or
+screenshot producer is missing, preserve the runner's precise capability
+blocker instead of silently changing automation strategy.
+
+Cleanup is scoped to the runner-owned POSIX process group; attached applications
+remain externally owned.

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

@@ -0,0 +1,29 @@
+# Desktop detail: macOS Accessibility
+
+Load this topic only when `selection.guide.topic` is `macos-accessibility`.
+
+The trusted bundled driver uses macOS Accessibility for semantic discovery and
+interaction, CGWindow for window correlation/capture support, and
+ScreenCaptureKit for exact-window recording when available. Do not invoke those
+APIs directly from the QA child.
+
+`target.application` may identify one application by `pid`, `name`, `bundleId`,
+or a bounded runner-owned `launch` contract. Launch wrappers remain inside the
+owned POSIX process group so the runner can correlate the real GUI descendant
+and perform scoped cleanup.
+
+Accessibility permission is required for semantic QA. Exact-window screenshots
+require Screen Recording permission; exact-window MP4 additionally requires
+the ScreenCaptureKit window-stream capability. Probe advertises these
+independently and returns remediation when permissions/toolchain are missing.
+Never change macOS privacy settings from this child.
+
+Supported semantic actions/selectors are those in the desktop base guide.
+Prefer Accessibility roles/names/state as the oracle. Supported runs attempt a
+silent exact-window video automatically; no extra recording action is needed.
+The recorder scales the captured independent window to fill its Retina output
+surface, so the window rather than an oversized empty canvas is the visual
+evidence.
+
+Attached applications remain externally owned. For launched applications,
+cleanup is limited to the runner-owned process group and correlated GUI target.

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

@@ -0,0 +1,23 @@
+# Desktop detail: Windows UI Automation
+
+Load this topic only when `selection.guide.topic` is `windows-uia`.
+
+The trusted bundled PowerShell/.NET helper uses Windows UI Automation for
+semantic discovery, interaction, and state assertions. Exact-window PNG capture
+uses the bounded Win32 capture path exposed by that helper. The QA child must
+not execute arbitrary PowerShell automation itself.
+
+`target.application` may use `pid`, `name`, or a bounded runner-owned `launch`
+contract. `bundleId` is not a Windows identity. For launched applications the
+launcher PID is an owned process-tree root; UI Automation correlates the actual
+GUI descendant before interaction and the runner retains that GUI PID as an
+additional scoped cleanup root.
+
+Probe verifies that UI Automation can initialize in the current interactive
+desktop session and separately reports screenshot capability. Window video is
+currently unavailable and must remain an explicit missing capability rather
+than being synthesized from screenshots.
+
+Use the common desktop semantic actions/selectors. Prefer UIA role/name/state
+oracles, retain PNG evidence when available, and never terminate an externally
+attached application or an unrelated process with the same name.

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

@@ -0,0 +1,54 @@
+# Native desktop backend router
+
+Load this guide only after the common UI-QA role classified the requested
+surface as `desktop`. Use the unified runner and its semantic desktop driver;
+do not choose a platform automation stack yourself.
+
+## Route by probe result
+
+Desktop routing is capability-probed from the actual host. Write the common
+flow, run `probe`, then load exactly the topic returned in `selection.guide`:
+
+```sh
+node "$PI_UI_QA_RUNNER" guide --backend desktop --topic macos-accessibility
+node "$PI_UI_QA_RUNNER" guide --backend desktop --topic windows-uia
+node "$PI_UI_QA_RUNNER" guide --backend desktop --topic linux-at-spi
+```
+
+Do not infer this topic from a project name or merely from the OS label. The
+probe also verifies runtime dependencies/permissions. If it returns `BLOCKED`,
+relay `blockedHandoff` and stop instead of installing automation packages,
+changing privacy/accessibility settings, or substituting another surface.
+
+Before `run`, the loaded topic must equal the authoritative `selection.guide`.
+
+## Common desktop flow
+
+Set `target.application` to exactly one supported identity/launch contract. The
+detail guide documents any platform-specific identity restrictions. Common
+steps are:
+
+- window/control: `waitForWindow`, `activateWindow`, `activate`;
+- inspection: `snapshotAccessibility`;
+- input: `setValue`, `inputText`, `pressKey`;
+- assertions: `waitForText`, `assertText`, `assertState`;
+- evidence: `screenshot`, `capture`.
+
+Semantic selectors use `path` or `name`, with optional `role` and `occurrence`.
+Prefer stable application-owned names/roles/labels/IDs over coordinates.
+
+Launch contracts must remain runner-owned and bounded. The runner permits only
+the documented safe environment subset plus `PI_UI_QA_*` bootstrap variables
+and injects `PI_UI_QA=1`. Do not daemonize the app or deliberately move it
+outside the ownership boundary.
+
+## Oracles, evidence, cleanup
+
+Prefer accessibility/app-driver state, window/dialog state, visible copy, and
+enabled/checked/value state as deterministic oracles. Screenshots/videos are
+supporting evidence. Repeated evidence actions may omit names; the runner gives
+them collision-free filenames.
+
+Inspect representative screenshots before visual claims. Let the runner clean
+up only processes/windows it launched. Attached applications are externally
+owned and must not be terminated; never broadly kill by application name.

package/external/pi-tools-suite/src/async-subagents/agents/ui-qa/guides/tui-native-terminal.md

@@ -0,0 +1,59 @@
+# TUI detail: native terminal
+
+Load this topic only when the TUI router or `selection.guide` selected
+`native-terminal`. Set `target.command.presentation: "native-terminal"`.
+
+## Presentation contract
+
+The target still runs directly in the runner-owned PTY used for deterministic
+input and semantic assertions. The runner mirrors that exact PTY byte stream
+through a private authenticated local bridge into a fresh owned native terminal
+window. Target argv/cwd/env are never typed into or embedded in a terminal
+shell; the native window bootstrap contains only the trusted bridge plus
+runner-generated transport parameters.
+
+The runner discovers a native terminal host from current machine capabilities,
+not project identity. Current platform providers are:
+
+- macOS: iTerm2 when installed, otherwise Terminal.app;
+- Windows: Windows Terminal;
+- Linux: kitty, then Alacritty, GNOME Terminal, Konsole, then xterm.
+
+The presentation is available only when the correlated platform desktop driver
+can also capture the owned terminal window. Missing host/dependency/permission
+returns `BLOCKED`; do not downgrade to headless evidence when pixel fidelity is
+part of the requested proof.
+
+## Flow surface
+
+Supported PTY-semantic actions are:
+
+- stability/navigation: `waitForStable`, `waitForText`;
+- input: `sendText`, `sendKeys`;
+- assertions: `assertText`, `assertNotText`, `assertCursor`,
+  `assertProcessRunning`, `assertProcessExited`;
+- evidence: `capture`.
+
+`viewport` and `resize` are intentionally unavailable because the actual native
+terminal geometry and owned PTY must stay synchronized. Never simulate a resize
+that the real window did not perform.
+
+Both automated input and terminal-protocol responses flow through the same PTY,
+so semantic assertions and native visual evidence refer to one target instance.
+After input, wait for observable/stable state before asserting or capturing.
+
+## Evidence semantics
+
+Headless screen captures and asciicast are retained only as semantic diagnostic
+evidence and the replay is marked diagnostic-only. Each `capture` also retains
+a real exact-window screenshot; those pixels are the visual source of truth for
+rendering claims. macOS can additionally publish bounded exact-window MP4 when
+Screen Recording/ScreenCaptureKit are available. Windows/Linux currently do not
+advertise native-terminal window video.
+
+Real-window evidence still does not replace deterministic PTY assertions.
+Inspect at least one meaningful screenshot before claiming colors/layout/glyph
+fidelity.
+
+Cleanup is scoped to the owned target PTY, private bridge, and fresh terminal
+host. Never attach to or close an unrelated user terminal window.

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

@@ -0,0 +1,37 @@
+# TUI detail: PTY
+
+Load this topic only when the TUI router or `selection.guide` selected `pty`.
+Set `target.command.presentation: "pty"` explicitly in new flows.
+
+## Flow surface
+
+The runner drives one real pseudo-terminal and maintains a bundled headless
+ANSI/VT screen model. Supported actions are:
+
+- stability/navigation: `waitForStable`, `waitForText`;
+- input: `sendText`, `sendKeys`, `resize`;
+- assertions: `assertText`, `assertNotText`, `assertCursor`,
+  `assertProcessRunning`, `assertProcessExited`;
+- evidence: `capture`.
+
+`sendKeys` uses documented named keys; do not embed control characters into
+model-authored text. Optional `viewport` supplies `cols`/`rows`, and `resize`
+may change them when terminal dimensions are part of the product contract.
+
+After input expected to change the screen, prefer `waitForText` or
+`waitForStable` before the corresponding assertion/capture. Cursor and process
+assertions are valid only when that state itself is part of the user-visible
+acceptance criterion.
+
+## Evidence semantics
+
+Every PTY run automatically publishes a bounded asciicast v2 replay. It is a
+terminal-state chronology, not pixel evidence: do not claim exact colors,
+fonts, glyph rendering, or native window geometry from it. `capture` retains the
+headless screen state for diagnosis.
+
+If exact rendered terminal visuals are required, this is the wrong route; use
+`native-terminal` rather than treating a headless rerender as visual proof.
+
+Cleanup terminates only the runner-owned PTY/target. Do not signal unrelated
+processes.

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

@@ -0,0 +1,60 @@
+# Terminal/TUI backend router
+
+Load this guide only after the common UI-QA role classified the requested
+surface as `tui`. The actual program must run through the unified runner's owned
+PTY; never replace an interactive UI request with captured stdout from another
+CLI path.
+
+## Choose one presentation route
+
+Choose from the user-facing acceptance surface, never from an application or
+repository name:
+
+- line-oriented/plain terminal or deliberately protocol-focused checks where
+  text/cursor/process/resize/ANSI semantics are the product -> `pty`;
+- structured/full-screen terminal UI where rendered layout, colors, glyphs,
+  menus, wrapping, clipping, focus, or terminal-window fidelity matter ->
+  `native-terminal`.
+
+Load exactly one detail topic:
+
+```sh
+node "$PI_UI_QA_RUNNER" guide --backend tui --topic pty
+node "$PI_UI_QA_RUNNER" guide --backend tui --topic native-terminal
+```
+
+For every new flow, explicitly set `target.command.presentation` to the route
+you selected. Omission remains accepted only for old-flow compatibility. If the
+requested visual fidelity requires `native-terminal` and probe blocks it, relay
+the blocker rather than silently downgrading to PTY evidence.
+
+After `probe`, `selection.guide` is authoritative and must equal the detail
+topic you are following before `run`. If it differs, load the returned topic and
+reconcile the flow first.
+
+## Common TUI flow
+
+Set `target.command` to the bounded argv/cwd/env launch contract for the actual
+shipping interactive program. Generic shells, arbitrary utility launchers, and
+inline-code execution are not an automation escape hatch. The runner launches
+the target directly in its owned PTY.
+
+Input must be user-equivalent. Define the expected visible/interactive
+postcondition before sending keys, and wait for observable text or a stable
+frame before asserting asynchronous state changes. The detail guide defines the
+supported actions and evidence for its presentation.
+
+Use only the documented bounded environment fields and project-local launch
+paths. Do not edit product source/tests/settings or signal/mutate target state
+behind the UI merely to make the flow pass.
+
+## Oracles, evidence, cleanup
+
+Deterministic terminal text/cursor/process assertions are the pass/fail oracle
+when those states are product-visible. Pixel captures and terminal recordings
+explain the result and do not replace assertions. Preserve failing evidence.
+
+Let the runner clean up only the PTY/process and presentation resources it owns.
+Never attach to, type into, or broadly terminate unrelated user terminal
+windows/processes. Report every retained artifact and inspect representative
+PNG evidence before making visual rendering claims.