@bacnh85/pi-ux 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.6.0 (2026-09-17)
+
+### Added
+
+- **`ux_audit` accepts `path`** — audit a CSS file verbatim (absolute or
+  cwd-relative) instead of retyping it into the `css` string. Incident-driven:
+  retyped/condensed CSS drifted (inlined DESIGN.md shadow values, mislabeled
+  colour pairs) and produced false gate failures and false confidence.
+  Exactly one of `path`/`css`; the tool guidance now leads with
+  "NEVER retype CSS when the file is on disk".
+
+### Changed
+
+- **ux-capture skill**: new Interaction section — `web_interact` (pi-web
+  ≥0.16.0) as the default path for behavior verification, with the manual CDP
+  recipe (trusted input, double-unwrap, clipboard activation caveats) as
+  fallback; honest sub-500px capture + `reduced_motion` documented as native
+  pi-web behavior; the iframe-wrapper layout probe demoted to a manual-capture
+  fallback.
+- **ux-design skill** Step 4: render-and-inspect loop gains "Interact &
+  verify" — click the primary CTA, submit the form, read back state with
+  `web_interact` before the audit gate.
+
 ## 0.5.0 (2026-09-16)
 
 ### Added

package/README.md

@@ -60,9 +60,12 @@ The **Direction playbook** ships in the skill as the positive layer: a typograph
 Deterministic slop-audit — no model needed, all gates are computable:
 
 ```
-ux_audit css="..." pairs=[{fg:"#111",bg:"#fff",label:"body",weight:400,size:16,min:4.5}]
+ux_audit path="web/src/app.css" pairs=[{fg:"#111",bg:"#fff",label:"body",weight:400,size:16,min:4.5}]
+ux_audit css="..." pairs=[...]
 ```
 
+Pass `path` to a stylesheet file — it is audited **verbatim**. Never retype or condense CSS into the `css` string when the file is on disk: retyped copies drift (inlined tokens, mislabeled pairs) and cause false gate failures or false confidence. Exactly one of `path`/`css`.
+
 | Gate | What it checks |
 |------|----------------|
 | **Contrast (APCA)** | Perceptual APCA Lc per fg/bg pair (Lc ≥75 body, ≥45 large-bold, ≥30 non-text). hex or `oklch()`. Optional `weight`/`size` set the threshold. WCAG 2.x ratio shown as a compliance sidecar. |

package/extensions/index.js

@@ -1,4 +1,6 @@
 import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
 
 const require = createRequire(import.meta.url);
 const {
@@ -67,9 +69,13 @@ function auditParametersSchema() {
     type: "object",
     additionalProperties: false,
     properties: {
+      path: {
+        type: "string",
+        description: "Path to a CSS stylesheet file to audit verbatim (absolute or cwd-relative). PREFERRED over retyping `css` — retyped copies drift (inlined tokens, mislabeled pairs) and cause false audit failures. Exactly one of path/css.",
+      },
       css: {
         type: "string",
-        description: "CSS stylesheet content to audit (inline stylesheets, styled-components output, or a concatenated .css file).",
+        description: "CSS stylesheet content to audit (inline stylesheets, styled-components output, or a concatenated .css file). Prefer `path` for on-disk files. Exactly one of path/css.",
       },
       pairs: {
         type: "array",
@@ -92,6 +98,23 @@ function auditParametersSchema() {
   };
 }
 
+/**
+ * Resolve the stylesheet to audit: a file `path` read verbatim (preferred —
+ * retyped `css` drifts and causes false gate failures) or inline `css`.
+ * Exactly one of the two.
+ */
+export function resolveAuditCss(params, cwd) {
+  const css = typeof params.css === "string" ? params.css : "";
+  const hasCss = css.trim().length > 0;
+  const p = typeof params.path === "string" ? params.path.trim() : "";
+  if (hasCss && p) throw new Error("Pass exactly one of `path` or `css` — not both.");
+  if (!hasCss && !p) throw new Error("Pass a stylesheet to audit: `path` (preferred, read verbatim) or `css`.");
+  // Relative paths resolve against the tool-call cwd (falls back to the
+  // process cwd) — the session cwd can differ from this process's cwd.
+  if (p) return fs.readFileSync(path.resolve(cwd || process.cwd(), p), "utf8");
+  return css;
+}
+
 export function formatAuditResult(result) {
   const lines = [];
   lines.push(result.pass ? "✅ UX AUDIT PASSED" : "❌ UX AUDIT FAILED");
@@ -173,6 +196,7 @@ export default function uxExtension(pi) {
       "Run deterministic slop-audit gates on CSS: APCA contrast (perceptual; WCAG sidecar), off-system token values (hardcoded hex / ad-hoc shadows), missing interaction states (:focus-visible / :disabled + prefers-reduced-motion), and named AI slop tells (glassmorphism, gradient orbs, neon glow, default-card, tracked-out eyebrows, tinted near-black). No model needed — all gates are computable. In strict mode, handoff is blocked until this passes. AUDIT THE COMPLETE STYLESHEET, not fragments. If no contrast pairs are supplied, they are auto-extracted from rules that declare both colour and background.",
     promptSnippet: "Run deterministic UX slop-audit (APCA contrast + tokens + states + slop tells)",
     promptGuidelines: [
+      "Pass `path` to the stylesheet file — it is audited verbatim. NEVER retype or condense CSS into the `css` string when the file is on disk: retyped copies drift (inlined DESIGN.md shadow values, mislabeled pairs) and produce false failures or false confidence.",
       "Contrast, token-coverage, and slop-tells are computable, not judgement — use this tool instead of eyeballing or calling a vision model.",
       "Pass fg/bg colour pairs (hex or oklch()) + optional weight/size to set the APCA threshold; the WCAG ratio is shown as a compliance sidecar. Omit pairs and they are auto-extracted from colour+background rules — but hand-picking catches text-on-inherited-backgrounds that auto-extraction misses.",
       "Audit the COMPLETE stylesheet — fragment input falsely fails the States gate (no interactive selectors present) and misses off-system values elsewhere.",
@@ -180,8 +204,8 @@ export default function uxExtension(pi) {
       "State coverage flags interactive elements (button/a/input/...) missing :focus-visible or :disabled rules.",
     ],
     parameters: auditParametersSchema(),
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const css = typeof params.css === "string" ? params.css : "";
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const css = resolveAuditCss(params, ctx?.cwd);
       const pairs = Array.isArray(params.pairs) ? params.pairs : [];
       const result = audit({ css, pairs });
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-ux",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Anti-slop UI/UX design discipline for your Pi agent — anchors a lintable DESIGN.md, derives a design direction (mood, type voice, color mood, signature), runs deterministic slop-audit gates (APCA contrast + tokens + states + slop tells), works with text-only models, ships reference design-system presets.",
   "keywords": [
     "pi-package",

package/skills/ux-capture/SKILL.md

@@ -12,8 +12,9 @@ description: >
 
 Judge captures at viewer resolution (1×–3×); never chase sub-visible precision.
 
-**Disable entrance animations when capturing**: add
-`--force-prefers-reduced-motion` to headless Chrome (or emulate the media
+**Disable entrance animations when capturing**: pass `reduced_motion=true` to
+`web_screenshot` / `web_interact` (pi-web ≥0.16.0), or add
+`--force-prefers-reduced-motion` to manual headless Chrome (or emulate the media
 query). Pages rightly use staggered page-load reveals with `opacity:0`
 backwards-fill — captured mid-animation they screenshot as blank sections,
 and you will "fix" content that isn't broken. The same forced query doubles
@@ -22,15 +23,56 @@ fully visible and readable.
 
 **Capture at the brief's target viewport.** Web pages: 1280–1440 wide. App
 screens and mobile-first briefs: the width the brief names (usually 390) at
-its target height (~844) — but know your tooling: many headless Chrome builds
+its target height (~844). pi-web handles this honestly now: `web_screenshot`
+and `web_interact` with `width`/`viewport` below 500px automatically use CDP
+device-metrics emulation (true 390px CSS viewport) and return a
+`scrollWidth`/`innerWidth` probe — `scrollWidth > width` means overflowing CSS.
+If you fall back to manual headless Chrome, know its trap: many builds
 **clamp window width to 500px**, so a "390 capture" secretly renders at 500
 and crops (see the layout probe below for the wrapper that does it honestly).
 If content overflows or dead-ends at the target size, the page is broken —
 **fix the page. Never widen the viewport to make a problem invisible.**
 
-## Layout probe (required for fixed-viewport briefs)
+## Interaction — web_interact (pi-web ≥0.16.0)
+
+A screenshot proves the page LOOKS right; only interaction proves it WORKS.
+After visual inspection, verify behavior with `web_interact` — one call = one
+browser lifecycle: open `url`, run `steps` in order, get per-step results, a
+final inline PNG, and a scrollWidth probe.
+
+```text
+web_interact url="http://localhost:5173" viewport={width:390,height:844} \
+  reduced_motion=true grant=["clipboard-read","clipboard-write"] steps=[
+  {click: "#copy-btn"},
+  {evaluate: "document.getElementById('status').textContent", label: "status"},
+  {type: {selector: "#email", text: "a@b.co"}},
+  {press: "Enter"},
+  {wait_for: "[data-success]"}
+```
 
-Two Chrome facts make naive mobile checks lie:
+- **Trusted clicks**: steps click via CDP `Input.dispatchMouseEvent` at the
+  element's center — synthetic `el.click()` grants no user activation, so
+  `document.execCommand('copy')` and login/clipboard flows would silently fail
+  under it. Under a trusted click, copy returns true.
+- **evaluate is double-unwrapped**: `Runtime.evaluate` nests the value at
+  `{result:{result:{value}}}` — the tool returns the real value; if you ever
+  hand-roll CDP, single-unwrapping yields `undefined` and makes the app LOOK
+  broken when it isn't.
+- Steps stop at the first failure with the reason — a broken selector surfaces
+  loudly instead of no-op'ing later steps.
+- Clipboard readback on insecure origins: there is no clipboard API to read
+  back with; `execCommand` returning true under a trusted click is the
+  strongest available signal (grant permissions for secure origins).
+
+Manual CDP (fallback only, when web_interact is unavailable): launch Chrome
+with `--remote-debugging-port=0`, read `<profile>/DevToolsActivePort` for the
+ws URL, create targets over the websocket (`Target.createTarget` — not the
+`/json/new` HTTP endpoint, whose method flipped to PUT), attach with
+`flatten: true`.
+
+## Layout probe (fallback for manual captures)
+
+Needed only when CDP tooling above is unavailable. Two Chrome facts make naive mobile checks lie:
 
 1. **Headless Chrome clamps window width to 500px.** A `--window-size=390`
    capture renders the page at 500px and crops the PNG to 390 — cuts at the
@@ -84,17 +126,22 @@ probe): `npm i puppeteer-core` once, then launch with
 Probe with `document.documentElement.scrollWidth` via `page.evaluate` before
 screenshotting; `page.screenshot({ fullPage: true })` for the tall capture.
 
-## Default — web_screenshot (pi-web ≥0.7.0, auto local detection)
+## Default — web_screenshot (pi-web ≥0.16.0, auto local detection)
 
 `web_screenshot` auto-routes localhost/LAN/file URLs to the locally installed
 headless Chrome and returns the PNG inline — no daemon, no manual commands:
 
 - `web_screenshot url="http://localhost:PORT" width=390 height=844` — the
-  model sees the render; pass `width`/`height` explicitly for mobile targets.
+  model sees the render; below 500px the capture is CDP device-emulated
+  (honest viewport, no clamp) and includes the scrollWidth probe.
+- `reduced_motion=true` disables entrance animations for the shot.
 - `full_page=true` captures a tall 8000px window; `wait_for` settles JS via
   `--virtual-time-budget`; `engine="local"` forces local on a public URL.
 - `web_pdf` works the same way (`--print-to-pdf`) for full-content archival.
 - If Chrome is missing: `web_status` shows `localChrome.path`; set `CHROME_PATH`.
+- Empty replies / connection resets from a dev-server URL usually mean a
+  STALE HUNG server on the port (accepts TCP, returns nothing) — `lsof -ti
+  :PORT` and kill it before diagnosing the tools.
 
 ## Fallback — manual headless Chrome (pi-web <0.7.0 or if the tool errors)
 

package/skills/ux-design/SKILL.md

@@ -136,8 +136,9 @@ even when `ux_audit` passes. (Text-only models, or genuinely no capture path
    - **Timidity:** cover the logo — could this page belong to anyone? Then amplify the display scale or the signature; the direction is not coming through.
    - **Type & overflow at target width:** display sizes actually large? measure comfortable? **any horizontal scroll, cut-off text, or squeezed badges at the target width?** orphans, cramped labels?
    - **Mood:** is the palette's temperature visible at a glance, or is it generic white+blue?
-4. **Visibility baseline.** Judge at what a viewer sees at 1×–3×. Nothing sub-visible can fail, and nothing sub-visible may be produced — no ±1px claims, no per-pixel diffs, no instrument-read values on either side.
-5. **Gates stay final.** `ux_audit` (Step 5) remains the blocking authority; vision settles only what looking can settle.
+4. **Interact & verify** — a screenshot proves looks, not behavior. Drive the page with `web_interact` (pi-web ≥0.16.0): click the primary CTA, submit the form, toggle a control, and read back state — steps stop at the first failure with the reason. Trusted CDP clicks grant user activation, so clipboard/login flows behave for real.
+5. **Visibility baseline.** Judge at what a viewer sees at 1×–3×. Nothing sub-visible can fail, and nothing sub-visible may be produced — no ±1px claims, no per-pixel diffs, no instrument-read values on either side.
+6. **Gates stay final.** `ux_audit` (Step 5) remains the blocking authority; vision settles only what looking can settle.
 
 ### Step 5 — Slop-audit gate (blocks handoff on fail)