ugly-app 0.1.489 → 0.1.490

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.489";
+export declare const CLI_VERSION = "0.1.490";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.489";
+export const CLI_VERSION = "0.1.490";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-app",
-  "version": "0.1.489",
+  "version": "0.1.490",
   "type": "module",
   "main": "./dist/server/index.js",
   "exports": {

package/src/cli/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.489";
+export const CLI_VERSION = "0.1.490";

package/templates/.claude/skills/bot-swarm/SKILL.md

@@ -231,9 +231,9 @@ Dispatch ALL active personas as **parallel subagents** (`delegate_parallel`). If
    node bots/feedback/run-bot.mjs {slug} --capture
    ```
 
-   This writes fresh PNGs + element maps to `bots/journal/cycles/screenshots/{slug}/<page>.png` and `<page>.element-map.json` reflecting the CURRENT site. No feedback is submitted yet.
+   This writes fresh PNGs + element maps to `bots/journal/cycles/screenshots/{slug}/<page>.png` and `<page>.element-map.json` reflecting the CURRENT site. **As of ugly-app 0.1.489 the driver also writes `<page>.ux-report.json`** — a structured `UglyInspectReport` capturing layout shift, animation jank, overlapping interactive controls, safe-area violations, and mobile keyboard coverage during a measurement window that includes the page's default interaction script (click first interactive `[data-id]`, wait, scroll). No feedback is submitted yet.
 
-3. **LOOK at each page.** For each PNG under `bots/journal/cycles/screenshots/{slug}/`, inspect it using vision — the persona **must actually see** the page before writing findings:
+3. **LOOK at each page AND READ the UX report.** For each PNG under `bots/journal/cycles/screenshots/{slug}/`, inspect it using vision — the persona **must actually see** the page before writing findings — AND read the sibling `<page>.ux-report.json` to ground the visual critique in measured defects:
 
    - If `analyze_image` is available (ugly-studio coding-agent):
 
@@ -251,6 +251,15 @@ Dispatch ALL active personas as **parallel subagents** (`delegate_parallel`). If
 
    - Cross-reference with the matching `<page>.element-map.json` to resolve specific `dataId` / source-file references when you find something worth reporting.
 
+   - **Mine `<page>.ux-report.json`** for objective defects the screenshot alone cannot show. Treat each of these as a finding worth a feedback row — quote the offending selector in the message:
+     - `safeAreaViolations[]` → `{ "type": "bug", "message": "<selector> spills outside iOS safe area on <side> edge" }`
+     - `overlaps[]` → `{ "type": "design", "message": "<a.selector> and <b.selector> overlap by Npx — likely a z-index or layout bug" }`
+     - `keyboard.coveredInputs[]` → `{ "type": "bug", "message": "<selector> is covered by the on-screen keyboard when focused" }`
+     - `cls.total > 0.1` → `{ "type": "design", "message": "page shifts significantly during load: <cls.total> across N spikes" }`
+     - `animations[].droppedFrames > 2` → `{ "type": "bug", "message": "<element> animation drops M frames over Tms" }`
+
+     Visual critique still flows from the screenshot — the structured signals add the movement-and-mobile dimension a single frame can't show.
+
    **Hard rule — no exceptions, including cycle 001:** every active persona must perform ≥1 vision call (`analyze_image` or Read on a PNG) against its **own** captured screenshots before its findings.json is written. Writing findings.json for a persona without a logged vision call for that same persona is a **cycle failure** — stop the cycle and surface it. "All bots see the same blank canvas, I'll just author findings in a batch" is the exact shortcut this rule exists to prevent: feedback authored from imagination instead of from what the persona actually saw is dead weight that pollutes the swarm's signal.
 
 4. **AUTHOR findings.json.** Write 1–5 findings to `bots/feedback/active/{slug}/findings.json`:

package/templates/.claude/skills/verify-ux/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: verify-ux
+description: Probe the running app for objective UX defects (CLS, animation jank, control overlap, safe-area violations, keyboard covering inputs) after UI changes
+user-invocable: true
+---
+
+After meaningful UI changes — new page, new popup, layout edits, animation work, mobile preview switch — call `inspect_ux` and act on what it finds. Don't declare UI work done without one clean probe.
+
+## When to run
+
+- Created or edited a page → probe its primary route + each interactive flow
+- Added/modified a popup, modal, toast, or accordion → probe the open transition
+- Touched animations, transitions, or scroll-driven effects → probe with `actions` driving the trigger
+- Switched a screen to a new device profile → probe `device: 'ios'` and `device: 'android'`
+- Added a form with focusable inputs near the bottom of a page → probe `simulate_keyboard: true`
+
+## How to call
+
+`inspect_ux` runs `window.__uglyInspect()` inside an off-screen browser pointed at your session's dev server. Observers run continuously from page load; the tool reads a measurement WINDOW so you can drive interactions and see what happened during them.
+
+Examples:
+
+```ts
+// Initial page load on iOS
+inspect_ux({ url_path: '/feed', device: 'ios' })
+
+// SPA navigation jank
+inspect_ux({ actions: [{ click: '[data-id=settings-link]' }, { wait: 800 }] })
+
+// Popup entry transition
+inspect_ux({ url_path: '/profile', actions: [{ click: '[data-id=edit-btn]' }, { wait: 600 }] })
+
+// Mobile keyboard covering input
+inspect_ux({
+  url_path: '/signup',
+  device: 'ios',
+  actions: [
+    { focus: '[data-id=email-field]' },
+    { simulate_keyboard: true },
+    { wait: 400 },
+  ],
+})
+
+// Scroll-driven animations
+inspect_ux({ actions: [{ scroll: { to: 2000 } }, { wait: 1200 }] })
+```
+
+## What to act on
+
+The returned `UglyInspectReport` is structured JSON. Treat each of these as a build failure that must be fixed before declaring done:
+
+| Field | Defect threshold |
+|---|---|
+| `cls.total` | > 0.1 — significant layout shift during the window |
+| `longTasks[]` | Any entry > 100ms while an animation is in flight (`during` set) |
+| `overlaps[]` | Any entry — two interactive controls share screen space |
+| `safeAreaViolations[]` | Any entry — interactive element spills under notch / home indicator |
+| `keyboard.coveredInputs[]` | Any entry — focused input rendered behind the on-screen keyboard |
+| `animations[].droppedFrames` | > 2 dropped per animation |
+| `popups[].droppedFrames` | > 2 — popup entry stutters |
+
+For each defect:
+
+1. Quote the offending `selector` from the report in your fix description.
+2. Make the smallest CSS / layout change that resolves it (move the element inside the safe rect, raise z-index, defer the layout work, add a placeholder for async content, etc.).
+3. Re-run `inspect_ux` with the same arguments to confirm the defect is gone before moving on.
+
+## Don't
+
+- Don't use `inspect_ux` for *aesthetic* judgments ("does this look pretty?"). For those, use `dev_server_screenshot` + `analyze_image`. `inspect_ux` is for objective, measurable defects only.
+- Don't gate trivial fixes (typo, copy change, color tweak) on a clean inspect_ux run.
+- Don't accept "the report has overlaps but they're decorative" without checking — if the report flagged it, the elements are tagged as interactive (`[data-id]`, `[role]`, `button`, `input`, `a`).

package/templates/CLAUDE.md

@@ -106,6 +106,22 @@ Every endpoint is accessible via both WebSocket (`socket.request(name, input)`)
   versions which include accessibility attributes and element map support
 - **Always** set `aria-label` on icon-only buttons and non-text interactive elements
 
+## UX inspection (`window.__uglyInspect()`)
+
+Every page exposes a runtime inspection API installed by `bootstrapApp` at boot. It reports objective UX defects: layout shift (CLS), animation jank, overlapping interactive controls, safe-area violations, mobile keyboard coverage, popup mount cost, SPA route transitions. Observers run continuously from page load and keep a rolling 500-entry ring buffer per signal.
+
+**Call from:**
+- **Playwright tests / bots** — `import { inspectWindow, expectClean, setDevice, simulateKeyboard, waitForApp } from 'ugly-app/playwright'`
+- **Browser console during dev** — `window.__uglyInspect({ since?: number })` returns a `UglyInspectReport` JSON; `window.__uglyInspectMark()` returns a timestamp for windowed reads
+- **Studio coding agent** — call the `inspect_ux` tool with optional `actions[]` to drive navigation/clicks/keyboard before reading
+
+`UglyInspectReport` type and all entry types are exported from `ugly-app/client` and re-exported from `ugly-app/playwright` so tests don't have to reach into client code.
+
+**Rules:**
+- **Never** call `page.evaluate('window.__uglyInspect(...)')` directly — use `ugly-app/playwright` so renames and shape changes propagate
+- **Treat as build failures** in test code: any `safeAreaViolations`, `overlaps`, `keyboard.coveredInputs`, or `animations[].droppedFrames > 2`
+- The expensive scans (overlap, safe-area) only run when `__uglyInspect()` is called — observers themselves are essentially free
+
 ## Feedback system
 Feedback button is always at `[data-id="feedback-button"]` (bottom-right).
 User feedback history: `GET /my_feedback` (requires auth cookie).

package/templates/bots/feedback/run-bot.mjs

@@ -188,21 +188,65 @@ function routeFilenames(route) {
     slugForFile,
     screenshotPath: path.join(SCREENSHOTS_DIR, `${slugForFile}.png`),
     elementMapPath: path.join(SCREENSHOTS_DIR, `${slugForFile}.element-map.json`),
+    uxReportPath: path.join(SCREENSHOTS_DIR, `${slugForFile}.ux-report.json`),
     url: `${BASE_URL}${route}`,
   };
 }
 
 async function captureRoute(page, route) {
-  const { screenshotPath, elementMapPath, url } = routeFilenames(route);
+  const { screenshotPath, elementMapPath, uxReportPath, url } =
+    routeFilenames(route);
   try {
     await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
   } catch (err) {
     console.error(`[${SLUG}] failed to load ${url}: ${err.message}`);
     return false;
   }
+  // Open a UX measurement window, drive a default interaction script
+  // (click first interactive [data-id], wait, scroll halfway, back to
+  // top), then read window.__uglyInspect() inside the page so the
+  // report covers actual movement, not just static layout.
+  let uxReport = null;
+  try {
+    const mark = await page.evaluate(
+      () => window.__uglyInspectMark?.() ?? Date.now(),
+    );
+    // Default interaction: nudge the page so transitions / scroll-driven
+    // animations fire. Personas can override by editing this script
+    // alongside pages.json.
+    await page
+      .evaluate(async () => {
+        const firstInteractive = document.querySelector(
+          '[data-id]:not([data-id=feedback-button])',
+        );
+        if (
+          firstInteractive &&
+          firstInteractive.tagName !== 'INPUT' &&
+          firstInteractive.tagName !== 'TEXTAREA'
+        ) {
+          firstInteractive.click?.();
+        }
+        await new Promise((r) => setTimeout(r, 400));
+        window.scrollTo({ top: 800, behavior: 'smooth' });
+        await new Promise((r) => setTimeout(r, 600));
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      })
+      .catch(() => undefined);
+    await page.waitForTimeout(800);
+    uxReport = await page.evaluate(
+      (s) => window.__uglyInspect?.({ since: s }) ?? null,
+      mark,
+    );
+  } catch {
+    // window.__uglyInspect not installed (pre-0.1.489 ugly-app) — leave
+    // uxReport null so downstream skills can detect the absence.
+  }
   await page.screenshot({ path: screenshotPath, fullPage: true });
   const elementMap = await captureElementMap(page);
   fs.writeFileSync(elementMapPath, JSON.stringify(elementMap, null, 2));
+  if (uxReport) {
+    fs.writeFileSync(uxReportPath, JSON.stringify(uxReport, null, 2));
+  }
   return true;
 }
 

package/templates/client/allPages.ts

@@ -36,4 +36,8 @@ export const allPages = {
   ['test/worker']: lazyPage(() => import('./pages/WorkerTestPage')),
   ['test/strings']: lazyPage(() => import('./pages/StringsTestPage')),
   ['test/safe-area']: lazyPage(() => import('./pages/SafeAreaTestPage')),
+  ['test/inspect-fixture']: lazyPage(() => import('./pages/InspectFixturePage')),
+  ['test/inspect-fixture-other']: lazyPage(
+    () => import('./pages/InspectFixtureOtherPage'),
+  ),
 } satisfies PageMap<AppPages>;

package/templates/client/pages/InspectFixtureOtherPage.tsx

@@ -0,0 +1,14 @@
+import { PageLayout, Text } from 'ugly-app/client';
+
+/** SPA-nav target for inspect-fixture tests. */
+export default function InspectFixtureOtherPage() {
+  return (
+    <PageLayout>
+      <div style={{ padding: 16 }}>
+        <Text data-id="other-page-title" size="xl" weight="bold">
+          Other page
+        </Text>
+      </div>
+    </PageLayout>
+  );
+}

package/templates/client/pages/InspectFixturePage.tsx

@@ -0,0 +1,216 @@
+import { useEffect, useState } from 'react';
+import { Input, PageLayout, Text, useRouter } from 'ugly-app/client';
+
+/**
+ * Test fixture for `window.__uglyInspect()` / `ugly-app/playwright`.
+ * Each `?simulate=` value renders a known-bad layout so the inspect
+ * helper can assert "yes the report caught it".
+ *
+ * Used by:
+ *   - templates/tests/e2e/inspect.spec.ts (Tier 2 in the studio spec)
+ *   - the studio integration test in app/studio/tests/inspect-ux-end-to-end.test.ts (Tier 3)
+ */
+export default function InspectFixturePage() {
+  const router = useRouter();
+  const params =
+    typeof window === 'undefined'
+      ? new URLSearchParams()
+      : new URLSearchParams(window.location.search);
+  const simulate = params.get('simulate') ?? '';
+  const [delayedMounted, setDelayedMounted] = useState(false);
+
+  useEffect(() => {
+    if (simulate === 'cls') {
+      const t = setTimeout(() => setDelayedMounted(true), 400);
+      return () => clearTimeout(t);
+    }
+    return undefined;
+  }, [simulate]);
+
+  return (
+    <PageLayout>
+      <div
+        style={{
+          padding: 16,
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 12,
+        }}
+      >
+        <Text size="xl" weight="bold">
+          Inspect Fixture · simulate={simulate || 'none'}
+        </Text>
+
+        {/* Default content — always rendered so [data-id] selector fires */}
+        <button
+          data-id="nav-to-other"
+          onClick={() => router.push('test/inspect-fixture-other', {})}
+        >
+          Navigate to other page
+        </button>
+
+        <button
+          data-id="nav-to-cls-page"
+          onClick={() =>
+            router.push('test/inspect-fixture', { simulate: 'cls' })
+          }
+        >
+          Navigate (re-load) with CLS sim
+        </button>
+
+        {simulate === 'cls' && (
+          <>
+            {/* Forces a layout shift when the delayed block mounts and
+                shoves siblings down by ~240px. */}
+            {delayedMounted && (
+              <div
+                data-id="delayed-banner"
+                style={{
+                  height: 240,
+                  background: 'crimson',
+                  color: 'white',
+                  padding: 16,
+                }}
+              >
+                Delayed mount — pushes content down
+              </div>
+            )}
+            <div data-id="below-the-shift" style={{ padding: 24 }}>
+              This block moves when the delayed banner mounts.
+            </div>
+          </>
+        )}
+
+        {simulate === 'overlap' && (
+          <div style={{ position: 'relative', height: 200 }}>
+            <button
+              data-id="overlap-a"
+              style={{
+                position: 'absolute',
+                left: 40,
+                top: 40,
+                width: 160,
+                height: 60,
+              }}
+            >
+              Button A
+            </button>
+            <button
+              data-id="overlap-b"
+              style={{
+                position: 'absolute',
+                left: 120,
+                top: 60,
+                width: 160,
+                height: 60,
+              }}
+            >
+              Button B
+            </button>
+          </div>
+        )}
+
+        {simulate === 'safearea' && (
+          <button
+            data-id="fab"
+            style={{
+              position: 'fixed',
+              left: 16,
+              right: 16,
+              bottom: 0,
+              height: 56,
+              background: '#0a84ff',
+              color: 'white',
+              border: 0,
+            }}
+          >
+            Floating action button (no bottom safe-area padding)
+          </button>
+        )}
+
+        {simulate === 'keyboard' && (
+          <div style={{ paddingTop: 600 }}>
+            <Input
+              data-id="fixture-input"
+              value=""
+              onChange={() => {}}
+              placeholder="Focus me to test keyboard coverage"
+            />
+          </div>
+        )}
+
+        {simulate === 'jank' && <JankSim />}
+
+        {simulate === 'popup' && <PopupSim />}
+      </div>
+    </PageLayout>
+  );
+}
+
+function JankSim() {
+  const [running, setRunning] = useState(false);
+  return (
+    <>
+      <button
+        data-id="start-jank"
+        onClick={() => {
+          setRunning(true);
+          // Spawn a long task during the animation.
+          const start = performance.now();
+          while (performance.now() - start < 250) {
+            // Busy-loop — guaranteed long task.
+          }
+          setTimeout(() => setRunning(false), 1000);
+        }}
+      >
+        Start janky animation
+      </button>
+      {running && (
+        <div
+          data-id="janky-animation"
+          style={{
+            width: 100,
+            height: 100,
+            background: 'orange',
+            animation: 'spin 800ms linear',
+          }}
+        />
+      )}
+      <style>{`@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }`}</style>
+    </>
+  );
+}
+
+function PopupSim() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <button data-id="open-modal" onClick={() => setOpen(true)}>
+        Open modal
+      </button>
+      {open && (
+        <div
+          role="dialog"
+          data-id="modal-content"
+          style={{
+            position: 'fixed',
+            inset: 0,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: 'rgba(0,0,0,0.5)',
+            animation: 'fade-in 300ms ease',
+          }}
+        >
+          <div style={{ background: 'white', padding: 24, borderRadius: 8 }}>
+            <Text>Modal body</Text>
+            <button data-id="close-modal" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </div>
+      )}
+      <style>{`@keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }`}</style>
+    </>
+  );
+}

package/templates/shared/pages.ts

@@ -35,6 +35,10 @@ export const pages = definePages({
   'test/worker': definePage<{}>({ auth: true }),
   'test/strings': definePage<{}>({ auth: false }),
   'test/safe-area': definePage<{}>({ auth: false }),
+  'test/inspect-fixture': definePage<{
+    simulate?: 'cls' | 'overlap' | 'safearea' | 'keyboard' | 'jank' | 'popup';
+  }>({ auth: false }),
+  'test/inspect-fixture-other': definePage<{}>({ auth: false }),
 });
 
 export type AppPages = typeof pages;