@stacknyu/pi-glitch-lab 0.0.0-stage → 0.5.1

package/scripts/sensors/react_sensor.mjs

@@ -0,0 +1,167 @@
+/**
+ * React render sensor — runs inside the page, installed before any app script.
+ *
+ * It registers itself as (or wraps) window.__REACT_DEVTOOLS_GLOBAL_HOOK__, the same channel React DevTools
+ * uses, and on every commit records which components MOUNTED, RE-RENDERED or were REMOVED, where they sit on
+ * screen, and which props changed. From that it derives REMOUNTS: a component that is removed and a new
+ * instance of the same component appears in the same place (e.g. a sidebar rebuilt on every navigation,
+ * a chat box whose component type changes on every render).
+ *
+ * Works on production builds too, but component names are minified there (e.g. "a", "Xe"); a staging
+ * build with readable names gives much better reports.
+ *
+ * Data: window.__glReact = { available, commits, events: [...], counts }
+ *   event: { type: "mount"|"render"|"unmount"|"remount", t, name, rect, changed?, gapMs? }
+ */
+export function REACT_SENSOR() {
+  if (window.__glReact) return;
+  const S = (window.__glReact = { available: false, renderers: 0, commits: 0, events: [], dropped: 0, lastRect: new WeakMap() });
+  const MAX_EVENTS = 20000, MAX_VISIT = 5000, MAX_RECTS = 120;
+  const COMPOSITE = new Set([0, 1, 2, 11, 14, 15]); // Function, Class, Indeterminate, ForwardRef, Memo, SimpleMemo
+  const HOST = new Set([5, 26, 27]);                  // HostComponent, HostHoistable, HostSingleton
+  const push = (e) => { if (S.events.length < MAX_EVENTS) S.events.push(e); else S.dropped++; };
+
+  const nameOf = (type) => {
+    if (!type || typeof type === "string") return null;
+    if (typeof type === "function") return type.displayName || type.name || null;
+    if (type.displayName) return type.displayName;
+    if (type.render) return type.render.displayName || type.render.name || null;
+    if (type.type) return nameOf(type.type);
+    return null;
+  };
+  let lastHops = 0;
+  const hostOf = (fiber) => {
+    let f = fiber, depth = 0;
+    while (f && depth++ < 60) {
+      if (HOST.has(f.tag) && f.stateNode && f.stateNode.getBoundingClientRect) { lastHops = depth; return f.stateNode; }
+      f = f.child;
+    }
+    return null;
+  };
+  let rectBudget = 0;
+  const rectOf = (fiber) => {
+    if (rectBudget-- <= 0) return null;
+    const el = hostOf(fiber);
+    if (!el || !el.isConnected) return null;
+    const r = el.getBoundingClientRect();
+    if (!r.width || !r.height) return null;
+    // d = hops from the component to its first DOM element: wrappers that share the same element have a larger d
+    return { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height), d: lastHops };
+  };
+  const changedProps = (prev, next) => {
+    if (!prev || !next || prev === next) return [];
+    const keys = new Set([...Object.keys(prev), ...Object.keys(next)]);
+    const out = [];
+    for (const k of keys) if (k !== "children" && prev[k] !== next[k]) out.push(k);
+    if (prev.children !== next.children && out.length === 0) out.push("children");
+    return out.slice(0, 6);
+  };
+  // did any hook VALUE change? (hook objects are new on every render, so compare their values;
+  // effect hooks hold new effect objects each render and are ignored)
+  const isEffect = (v) => v && typeof v === "object" && "create" in v && "deps" in v;
+  const stateChanged = (fiber) => {
+    const a = fiber.alternate.memoizedState, b = fiber.memoizedState;
+    if (fiber.tag === 1) return a !== b;            // class component: new state object on setState
+    let x = a, y = b, n = 0;
+    while (x && y && n++ < 80) {
+      if (typeof x !== "object" || typeof y !== "object" || !("next" in x)) return x !== y;
+      if (x.memoizedState !== y.memoizedState && !(isEffect(x.memoizedState) && isEffect(y.memoizedState))) return true;
+      x = x.next; y = y.next;
+    }
+    return false;
+  };
+  const collectDeleted = (fiber, into, now) => {
+    // walk a deleted subtree and record composite components that went away
+    const stack = [fiber]; let n = 0;
+    while (stack.length && n++ < 800) {
+      const f = stack.pop(); if (!f) continue;
+      if (COMPOSITE.has(f.tag) && !reported.has(f) && !(f.alternate && reported.has(f.alternate))) {
+        reported.add(f);
+        const name = nameOf(f.type);
+        if (name) into.push({ name, rect: S.lastRect.get(f) || (f.alternate && S.lastRect.get(f.alternate)) || null, t: now });
+      }
+      if (f.child) stack.push(f.child);
+      if (f.sibling && f !== fiber) stack.push(f.sibling);
+    }
+  };
+
+  const recent = []; // recently removed composites: {name, rect, t}
+  const reported = new WeakSet(); // fibers already reported as removed (React may report via two channels)
+  const overlap = (a, b) => a && b && a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+
+  function onCommit(root) {
+    const now = Math.round(performance.now());
+    S.commits++;
+    rectBudget = MAX_RECTS;
+    const current = root && root.current;
+    if (!current) return;
+    const removed = [];
+    const mounts = [];
+    let visited = 0;
+    const walk = (fiber, mounting) => {
+      const stack = [[fiber, mounting]];
+      while (stack.length) {
+        const [f, isMount] = stack.pop();
+        if (!f || visited++ > MAX_VISIT) continue;
+        if (f.deletions && f.deletions.length) for (const d of f.deletions) collectDeleted(d, removed, now);
+        const composite = COMPOSITE.has(f.tag);
+        const name = composite ? nameOf(f.type) : null;
+        let descend = true;
+        if (isMount || !f.alternate) {
+          if (name) { const rect = rectOf(f); if (rect) S.lastRect.set(f, rect); mounts.push({ name, rect }); push({ type: "mount", t: now, name, rect }); }
+          if (f.child) stack.push([f.child, true]);
+        } else {
+          if (name && ((f.flags ?? f.effectTag ?? 0) & 1) === 1) { // PerformedWork => this component rendered in this commit
+            const rect = rectOf(f); if (rect) S.lastRect.set(f, rect);
+            const ch = changedProps(f.alternate.memoizedProps, f.memoizedProps);
+            const why = ch.length ? ch : stateChanged(f) ? ["(own state)"] : ["(parent re-rendered)"];
+            push({ type: "render", t: now, name, rect, changed: why });
+          }
+          // only descend where React actually re-processed children
+          descend = f.child !== f.alternate.child || !!(f.deletions && f.deletions.length);
+          // (flags on skipped subtrees are stale, so never descend into them)
+          if (f.child && descend) stack.push([f.child, false]);
+        }
+        if (f.sibling && f !== fiber) stack.push([f.sibling, isMount]);
+      }
+    };
+    try { walk(current, false); } catch (e) { S.error = String(e && e.message); }
+    for (const r of removed) { push({ type: "unmount", t: now, name: r.name, rect: r.rect }); recent.push(r); }
+    // remount = same component name removed and mounted again in (about) the same place within 2s
+    while (recent.length && now - recent[0].t > 2000) recent.shift();
+    for (const m of mounts) {
+      const idx = recent.findIndex((r) => r.name === m.name && (!r.rect || !m.rect || overlap(r.rect, m.rect)));
+      if (idx >= 0) { const r = recent.splice(idx, 1)[0]; push({ type: "remount", t: now, name: m.name, rect: m.rect || r.rect, gapMs: now - r.t }); }
+    }
+  }
+  function onUnmount(fiber) {
+    if (!COMPOSITE.has(fiber.tag) || reported.has(fiber) || (fiber.alternate && reported.has(fiber.alternate))) return;
+    reported.add(fiber);
+    const name = nameOf(fiber.type); if (!name) return;
+    const now = Math.round(performance.now());
+    const rect = S.lastRect.get(fiber) || (fiber.alternate && S.lastRect.get(fiber.alternate)) || null;
+    recent.push({ name, rect, t: now }); push({ type: "unmount", t: now, name, rect });
+  }
+
+  const existing = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (existing && typeof existing === "object") {
+    const oc = existing.onCommitFiberRoot, ou = existing.onCommitFiberUnmount;
+    existing.onCommitFiberRoot = function (id, root, ...rest) { try { S.available = true; onCommit(root); } catch {} return oc && oc.call(this, id, root, ...rest); };
+    existing.onCommitFiberUnmount = function (id, fiber, ...rest) { try { onUnmount(fiber); } catch {} return ou && ou.call(this, id, fiber, ...rest); };
+    return;
+  }
+  let nextId = 0;
+  const hook = {
+    renderers: new Map(),
+    supportsFiber: true,
+    isDisabled: false,
+    inject(renderer) { const id = ++nextId; this.renderers.set(id, renderer); S.renderers++; S.available = true; return id; },
+    onCommitFiberRoot(_id, root) { try { onCommit(root); } catch (e) { S.error = String(e && e.message); } },
+    onCommitFiberUnmount(_id, fiber) { try { onUnmount(fiber); } catch {} },
+    onPostCommitFiberRoot() {},
+    onScheduleFiberRoot() {},
+    setStrictMode() {},
+    checkDCE() {},
+  };
+  Object.defineProperty(window, "__REACT_DEVTOOLS_GLOBAL_HOOK__", { value: hook, configurable: true, writable: true });
+}

package/skills/ai-agentic-usability-testing/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ai-agentic-usability-testing
+description: "Browser UI/UX and deterministic UAT testing with Glitch Lab. Inventory rendered controls, explore authorized menu/tab/dialog/navigation states, test scripted acceptance criteria and report evidence/coverage. For dashboards and web apps. No AI calls in the execution scripts. Not exhaustive accessibility or native-device certification."
+---
+
+# UI/UX and UAT with Glitch Lab
+
+## Authorization first
+
+Use approved disposable environments and test accounts. Loading a page can itself change data. Never claim this is a read-only sandbox or that reloading rolls back server state.
+
+- Start `ux_affordance_scan` without `probeClicks`: observation only.
+- Before any click exploration or navigation glitch pass, obtain explicit user permission and set `interact=true`.
+- Login, typing, selects/checkboxes, submit/Enter and writes require separate permission and `allowWrites=true` as well.
+- Never infer authorization from tool availability or from a request for a report. In headless mode the caller supplies permission flags only after operator approval.
+- Run `glitch_lab_doctor` to check the browser. Install Chromium only when the user authorizes the download.
+
+## Configure
+
+Copy `assets/matrix.web.example.json` into `.ux/matrix.json`. Replace URL, target selectors and expected outcomes with the actual approved contract. Ask for missing business criteria; do not invent them.
+
+Use exact role/name or label locators; explicit selectors can identify controls with duplicate names. Missing/ambiguous targets fail. For login, use environment-variable credentials plus `login.authenticated` (an authenticated-only visible selector) and/or an exact non-root `login.waitFor` pathname. No login state is saved to disk. Keep `.ux/` ignored/private, configure masks, and review evidence for sensitive data before sharing.
+
+Optional education/finance personas in `assets/default-personas.md` and `matrix.default.json` are examples for those domains, not defaults to impose on unrelated apps. Their placeholders require calibration and updated positive authentication checks.
+
+## Pass 1 — inventory
+
+Call `ux_affordance_scan` with URL or config/cell. Read annotated screenshots and saved items:
+- labels, focusability, disabled/expanded/selected/checked state;
+- small, unlabeled or covered targets and horizontal overflow;
+- fake/hidden-button visual candidates, not proven failures;
+- scroll bounds and inaccessible/unexplored content.
+
+## Pass 2 — bounded interaction coverage
+
+After approval, call `ux_affordance_scan` with `probeClicks=true, interact=true`. Set page/state/action/depth/time bounds appropriate to the approved area.
+
+The explorer resets/replays parent states, discovers revealed menus/tabs/dialogs and records before/after evidence. It skips automatic input values and obvious submit/destructive controls. HTTP write blocking without allowWrites is defense in depth, not proof of no side effects. Repeated interactions can repeat writes if authorized.
+
+Distinguish responded, no-observable-response, error, blocked and skipped. A network request is not acceptance. No visible response may be valid for clipboard/hover controls or may need a longer observation window. Report limit hits and unvisited states; never claim every control works.
+
+## Pass 3 — scripted UAT
+
+Run `ux_journeys` for explicit business acceptance:
+1. Assert the expected loaded screen or authenticated user.
+2. Execute approved actions.
+3. Assert text/URL/visibility/value/checked/enabled/count/attribute outcomes.
+4. For an authorized persistence test, reload and assert the saved value.
+
+Use a keyboard `press` step for Tab/arrow/Enter tests. Fill/select/check/save require writes permission. Optional steps must not hide a required outcome. Negative persona/content checks belong after a positive loaded-state assertion; a login page is not proof that tenant gating works.
+
+Required failures, missing/empty journeys and missing baselines fail. Do not convert a tool error into a pass. A new baseline needs a new directory; never overwrite historical evidence. `measureResponse` must observe output and stable completion before its timeout.
+
+## Glitch pass
+
+Use `glitch_hunt` for flicker/remount/layout-shift concerns; read the glitch-hunt skill. Prefer production-like builds and repeated evidence. React sensor availability, sampling and minification limit attribution.
+
+## Report
+
+Use `ux_report` with run directory and optional written findings JSON. Include:
+- approved target, persona/device, scope and actions;
+- discovered/exercised control-state pairs, visited states, bounds and skipped/blocked reasons;
+- UAT criteria passed/failed and baseline provenance;
+- evidence paths and observed timing;
+- UX findings in plain language with recommendations;
+- gaps: iframe/shadow/virtualized/native/keyboard-only or other untested states.
+
+Keep execution evidence separate from interpretation. Simulated personas are not real-user usability research. No application code changes or extra journeys without authorization.

package/skills/ai-agentic-usability-testing/assets/default-personas.md

@@ -0,0 +1,96 @@
+# Default personas
+
+These are the built-in personas. Use them unless the user provides others. Each one is tested as a **direct user of the platform (no partner)** first; partner cells come later.
+
+When simulating a persona, stay in character: use their vocabulary, their device, their patience level, and their worries. Their "questions to ask the AI" are the exact words to type into chat.
+
+---
+
+## 1. `indian-germany-student` — Arjun, 22, wants a Master's in Germany
+
+- **Situation:** Final-year B.Tech (Computer Science) student at a private engineering college in Pune. CGPA 7.8/10. Wants an MS in Computer Science or Data Science at a public German university (TU Munich, RWTH Aachen, TU Berlin) for a winter intake. Middle-class family; cost matters a lot.
+- **Device:** Mid-range Android phone (360×800), Chrome; sometimes a college lab PC. Mobile data or hostel Wi-Fi (fast 3G-ish, drops often).
+- **Language:** Fluent but Indian English; may type in Hinglish ("how much blocked account amount needed bro"). Reads quickly, skims long paragraphs, screenshots things to send to family.
+- **Tech comfort:** High for apps (Instagram, UPI, WhatsApp), low patience for web forms.
+- **What he needs to figure out:** APS certificate, IELTS/TOEFL score (and whether German A1/B1 helps), GRE for some programs, uni-assist or direct application, SOP and LORs, blocked account (Sperrkonto) and health insurance, deadlines, DAAD scholarships, student visa, part-time work rules, total cost in ₹.
+- **Top tasks (his words):**
+  1. "What all documents and exams do I need for MS in Germany?" → wants a checklist he can save.
+  2. "Is my 7.8 CGPA enough for TU Munich? Which universities should I target?"
+  3. "How much money do I need in total, in rupees?" → wants a clear breakdown, maybe a widget/table.
+  4. Save everything as notes and come back tomorrow to continue.
+- **Success looks like:** A saved checklist with deadlines, and knowing exactly what to do this month.
+- **Frustrations:** Long generic answers; not knowing if something saved; buttons he can't identify on a small screen; losing a long chat when the network drops.
+- **Must NOT see:** tax, stock market, trading, portfolio, or finance-analyst agents/widgets; US-only admissions content presented as if it applied to him.
+- **Formats he expects:** ₹ with Indian grouping (₹12,50,000 or "12.5 lakh"), € conversions, dates as DD/MM/YYYY or "15 July".
+
+## 2. `us-ivy-applicant` — Emily, 17, aiming for Harvard or MIT
+
+- **Situation:** High-school junior in Austin, Texas. Strong in math and robotics club; unsure how to stand out. Parents are involved but busy. Applying next fall (Early Action / Restrictive Early Action is on her mind).
+- **Device:** iPhone (390×844) most of the time; school Chromebook (1366×768) for longer work.
+- **Language:** US English, casual, types fast, uses abbreviations ("EA vs REA?", "do APs matter"). Short attention span for walls of text.
+- **What she needs to figure out:** SAT/ACT (test-required again at both), AP/course rigor, extracurriculars and awards, Common App essay and supplements, recommendation letters, interviews, timeline month by month, MIT vs Harvard differences, financial aid basics.
+- **Top tasks (her words):**
+  1. "What do I need to get into MIT? Like what should I be doing junior year?"
+  2. "Make me a timeline until application deadlines" → wants a plan she can save and check off.
+  3. "Help me brainstorm my Common App essay" → iterative chat, saves drafts as notes.
+  4. "Compare Harvard and MIT for someone into robotics."
+- **Success looks like:** A month-by-month plan and an essay idea she's excited about, saved where she can find them.
+- **Frustrations:** Anything that looks "old" or corporate; unclear icons; not knowing which agent to use; slow AI responses on her phone.
+- **Must NOT see:** Indian/German admissions specifics as defaults (APS, uni-assist, blocked account), tax or stock content.
+- **Formats she expects:** US dates (MM/DD), US grading (GPA /4.0, SAT /1600).
+
+## 3. `us-finance-analyst` — Mark, 40, financial analyst checking out the platform
+
+- **Situation:** Corporate financial analyst living in suburban Columbus, Ohio. Married, two kids, W-2 income plus some freelance consulting (1099) and a rental property. Received an IRS notice last year and wants to be ready for a possible audit. Evaluating whether this platform is worth using.
+- **Device:** Desktop, 1440×900 (sometimes a 1920 monitor), Chrome, fast network.
+- **Behavior:** **Skims.** Clicks around quickly to "see what it can do" before committing: opens menus, hovers icons, opens widgets, tries a couple of chats. Judges the product in the first few minutes. Expects keyboard shortcuts, exports, and precise numbers.
+- **Language:** Professional US English, uses tax jargon correctly (Schedule C, Schedule E, 1099-NEC, quarterly estimates, CP2000, substantiation).
+- **Top tasks (his words):**
+  1. Explore the dashboard and features: "What does this thing actually do?"
+  2. "I got a CP2000 notice last year. What documentation should I prepare in case of an audit?"
+  3. "Help me plan quarterly estimated taxes for my consulting income this year." → wants a table/widget he can export.
+  4. Save a checklist and a plan as notes; export or copy them.
+- **Success looks like:** Understanding the product's value in under 5 minutes; a precise, exportable plan.
+- **Frustrations:** Fluff, unclear feature names, slow widgets, numbers without units or dates, uncertainty about data privacy when uploading tax documents, no clear "not tax advice / consult a CPA" framing where appropriate.
+- **Must NOT see:** student/admissions agents or widgets, Indian market content, INR formatting.
+- **Formats he expects:** $ with US grouping ($12,500.00), US dates, US tax-year terminology.
+
+## 4. `indian-market-analyst` — Indian stock market analyst, age 30–65
+
+One persona with two variants at the ends of the age range. Test both; many findings differ by age.
+
+### 4a. `indian-market-analyst-young` — Rahul, 32
+- **Situation:** Works at a Mumbai brokerage research desk; also trades personally (equity and some F&O). Checks markets constantly.
+- **Device:** Android phone (360×800) during market hours, fast 3G/4G in transit.
+- **Behavior:** Fast, impatient, glances at numbers, wants market overview immediately, jumps between chat and data.
+- **Top tasks (his words):**
+  1. "NIFTY and Bank NIFTY outlook for the coming week?"
+  2. "Should I book profits in IT stocks or hold? What are the key levels?"
+  3. Check market widgets (indices, sectors, watchlist) and see how fresh the data is.
+  4. Save a research note on a sector.
+
+### 4b. `indian-market-analyst-senior` — Suresh, 61
+- **Situation:** Semi-retired equity analyst in Ahmedabad; manages family portfolio, long-term investor (large-caps, mutual funds, dividends). Careful, reads everything.
+- **Device:** Laptop 1366×768 at **125% browser zoom** (reading glasses); sometimes a tablet. Moderate network.
+- **Behavior:** Slow and deliberate; reads labels fully; won't click something he doesn't understand; worried about pressing the wrong thing; distrusts anything that looks like a "tip".
+- **Top tasks (his words):**
+  1. "Give me an overview of the market today and what to watch this month."
+  2. "Is it a good time to add HDFC Bank and ITC for the long term?"
+  3. Read a research summary with sources and save it.
+  4. Find where previous notes and chats are.
+
+### Shared for 4a/4b
+- **Language:** Indian English; comfortable with NSE/BSE, NIFTY 50, SENSEX, F&O, SEBI, FII/DII, results season.
+- **Success looks like:** Clear, sourced views with the data's timestamp; clear framing that it isn't SEBI-registered investment advice; notes saved and easy to find.
+- **Frustrations:** Stale data without a timestamp, numbers without units, US-centric defaults, confident "buy/sell" tips without caveats, small text (4b), slow widgets (4a).
+- **Must NOT see:** student/admissions content, US tax content, $ or US formatting on Indian market data.
+- **Formats expected:** ₹ with lakh/crore (₹1,25,000; ₹3.2 crore), IST times, market-hours awareness (09:15–15:30 IST).
+
+---
+
+## Cross-persona checks to always include
+
+- Each persona sees only their vertical's agents, dashboard, widgets and suggestions (persona tagging works). A leak is S1.
+- Number, currency, date and time formats match the persona.
+- AI answers in sensitive areas (finance, tax, market advice) show appropriate, visible, non-intrusive disclaimers.
+- A first-time user of each persona can find: chat, notes, research, and their saved work, without help.

package/skills/ai-agentic-usability-testing/assets/findings.example.json

@@ -0,0 +1,56 @@
+{
+  "title": "Usability, glitch & reliability audit — direct users, 5 personas",
+  "subtitle": "Staging build · Arjun, Emily, Mark, Rahul, Suresh · no partner",
+  "summary": "Most confusion comes from three patterns: status chips that look like buttons, icon-only chat actions with no labels, and AI replies that show nothing for 2–4 seconds. On the health partner, a Tax agent from the finance vertical is visible to patients.",
+  "scorecard": [
+    {
+      "cell": "indian-germany-student@direct",
+      "journey": "Get the Germany MS checklist and save it",
+      "result": "friction",
+      "issues": [
+        "UX-002",
+        "UX-014"
+      ]
+    },
+    {
+      "cell": "us-finance-analyst@direct",
+      "journey": "First look: explore features",
+      "result": "friction",
+      "issues": [
+        "UX-005"
+      ]
+    }
+  ],
+  "patterns": [
+    {
+      "title": "Status chips look like buttons",
+      "findings": [
+        "UX-002",
+        "UX-007",
+        "UX-011"
+      ],
+      "description": "Filled, rounded chips (Scholarships, Pending, Verified) have the same look as primary buttons. Teens on mobile tap them repeatedly.",
+      "recommendation": "Give non-interactive chips a flat, outline-free, low-saturation style and never the primary brand color. Reserve filled brand color for actions only, in the design system."
+    }
+  ],
+  "findings": [
+    {
+      "id": "UX-014",
+      "title": "Sidebar blinks every time a page opens",
+      "category": "Visual glitch",
+      "severity": "S2",
+      "cells": [
+        "indian-germany-student@direct",
+        "indian-market-analyst-senior@direct"
+      ],
+      "screen": "/notes, /research, /dashboard",
+      "personaVoice": "Every time I open something the menu on the left disappears for a moment. Is it reloading? Did I lose something?",
+      "observation": "The left sidebar disappears for ~120 ms and reappears on every navigation (remount).",
+      "evidence": "glitch images at ~1.2 s after load on 3 screens; DOM remount of nav#sidebar",
+      "recommendation": "Keep the sidebar persistent across page changes; only the main content area should update.",
+      "screenshots": [
+        "indian-germany-student__direct/glitches/load_notes_glitch_01.png"
+      ]
+    }
+  ]
+}