ugly-app 0.1.820 → 0.1.821

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-app",
-  "version": "0.1.820",
+  "version": "0.1.821",
   "type": "module",
   "comment:files": "Allowlist what ships to npm. dist = runtime; src = sourcemap targets (dist/*.js.map reference ../../src/); templates = CLI scaffold. Everything else at repo root (.pgdata local Postgres, coverage, assets/icons sources, test/, test-results/) is excluded by omission. The !negations strip the scaffold's installed deps + cruft (templates/node_modules is 200MB+ and must never ship). package.json/README/LICENSE ship automatically.",
   "files": [
@@ -64,7 +64,7 @@
   },
   "scripts": {
     "prebuild": "node -e \"const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));require('fs').writeFileSync('src/cli/version.ts','// Auto-generated by prebuild — do not edit manually\\nexport const CLI_VERSION = '+JSON.stringify(p.version)+';\\n');\" && rm -rf dist",
-    "build": "tsc && chmod +x dist/cli/index.js && cp src/markdown/client/*.css dist/markdown/client/ && mkdir -p dist/cli/publish/recipes && cp -R src/cli/publish/recipes/. dist/cli/publish/recipes/ && esbuild src/inspect/agent/bundle-entry.ts --bundle --format=iife --platform=browser --minify --outfile=dist/inspect/agent-bundle.js && esbuild src/inspect/host-bundle-entry.ts --bundle --format=iife --platform=browser --minify --outfile=dist/inspect/host-bundle.js",
+    "build": "tsc && chmod +x dist/cli/index.js && cp src/markdown/client/*.css dist/markdown/client/ && mkdir -p dist/cli/publish/recipes && cp -R src/cli/publish/recipes/. dist/cli/publish/recipes/ && esbuild src/inspect/agent/bundle-entry.ts --bundle --format=iife --platform=browser --minify --outfile=dist/inspect/agent-bundle.js --footer:js='//# sourceURL=ugly-inspect-agent.js' && esbuild src/inspect/host-bundle-entry.ts --bundle --format=iife --platform=browser --minify --outfile=dist/inspect/host-bundle.js",
     "test": "vitest run",
     "test:e2e": "E2E=1 vitest run tests/cli/e2e-integration.test.ts",
     "test:e2e:full": "pnpm exec tsx tests/e2e/full-e2e.ts",

package/src/cli/version.ts

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

package/src/inspect/agent/perfAgent.ts

@@ -28,6 +28,26 @@ const LONG_TASK_WINDOW_COUNT = 5;
 const DROPPED_FRAME_THRESHOLD = 3;
 const MAX_PENDING_ANOMALIES = 10;
 const PROFILE_DURATION_MS = 1000;
+// The 1s self-profile costs ~250 stack captures. Anomalies can arrive back-to-back
+// (every long task fires one), so profiling every anomaly makes the agent a
+// meaningful share of the very load it is measuring. Snapshots are still captured
+// each time; only the call tree is rate-limited.
+const PROFILE_COOLDOWN_MS = 30_000;
+// Above this, a heartbeat gap is a discontinuity (suspension / sleep / throttled tick
+// racing `visibilitychange`), not event-loop lag. Comfortably above the largest block
+// we still want to report as a spike.
+const SUSPEND_GAP_MS = 10_000;
+
+/**
+ * A hidden page's timers are throttled by the browser — Chromium clamps them to 1s
+ * and, after ~5 minutes, to once per MINUTE. The heartbeat measures `now - expected`,
+ * so an idle backgrounded tab reports tens of seconds of "event-loop lag" and a
+ * saturated cpuPressure. That is a property of not being on screen, not of the page.
+ * Observed in production: a backgrounded tab converging on exactly ~60000ms of lag.
+ */
+function isHidden(): boolean {
+  return typeof document !== 'undefined' && document.hidden === true;
+}
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -83,10 +103,37 @@ class HeartbeatDetector {
     return this.lagSamples.reduce((a, b) => a + b, 0) / this.lagSamples.length;
   }
 
+  /**
+   * Drop the accumulated window and re-baseline. Called when the page is hidden (its
+   * timers are about to be throttled) and when it becomes visible again (the first
+   * tick after a throttled gap would otherwise register as a huge stall).
+   */
+  reset(now: number): void {
+    this.lastTick = now;
+    this.lagSamples.length = 0;
+    this.delayedSamples.length = 0;
+    this.blipCount = 0;
+  }
+
   /** Returns true when a fresh anomaly is detected (pressure just crossed threshold). */
   tick(now: number): boolean {
+    // A throttled tick measures the browser's scheduling policy, not the page's
+    // event loop. Re-baseline and record nothing.
+    if (isHidden()) {
+      this.reset(now);
+      return false;
+    }
     const expected = this.lastTick + HEARTBEAT_INTERVAL_MS;
     const lag = Math.max(0, now - expected);
+    // A gap this large is a discontinuity — process suspension, machine sleep, or a
+    // throttled tick that beat `visibilitychange` back to the queue. It is not a
+    // stall we could act on, and recording it poisons the trailing average for the
+    // next ~10s. Re-baseline instead. (A genuine multi-second block below this
+    // threshold is still reported as a spike.)
+    if (lag > SUSPEND_GAP_MS) {
+      this.reset(now);
+      return false;
+    }
     this.lagSamples.push(lag);
     if (this.lagSamples.length > HEARTBEAT_WINDOW_SAMPLES) this.lagSamples.shift();
 
@@ -135,7 +182,19 @@ class FrameBudgetMonitor {
   private rafId = 0;
   onJank: (() => void) | null = null;
 
+  /** Forget the last frame time so a hidden→visible gap isn't counted as jank. */
+  reset(): void {
+    this.lastFrame = 0;
+    this.dropCount = 0;
+  }
+
   private tick = (now: number): void => {
+    // rAF is suspended while hidden; the first frame back carries the whole gap.
+    if (isHidden()) {
+      this.reset();
+      this.rafId = raf(this.tick);
+      return;
+    }
     const delta = now - this.lastFrame;
     if (this.lastFrame > 0 && delta > 32) {
       this.dropCount++;
@@ -185,6 +244,7 @@ export class PerfAgent {
   private pendingAnomalies: PerfSnapshot['trigger'][] = [];
   private snapshots: PerfSnapshot[] = [];
   private profiling = false;
+  private lastProfileAt = 0;
   private lcpMs: number | undefined;
   private fcpMs: number | undefined;
   private _startup: {
@@ -240,9 +300,7 @@ export class PerfAgent {
               this.lcpMs = e.startTime;
             }
           }
-          // Fire on web-vitals long-task count too
-          const ltCount = vitals.longTasks?.length ?? 0;
-          if (ltCount + this.longTasks.count >= LONG_TASK_WINDOW_COUNT * 2) {
+          if (this.longTaskAnomalyDue(vitals)) {
             void this.captureAnomaly('long-task');
           }
         });
@@ -262,10 +320,39 @@ export class PerfAgent {
       }
     } catch { /* unsupported */ }
 
+    // Re-baseline across visibility changes. Going hidden, the next tick may be a
+    // minute late; coming back, that gap must not be charged to the page.
+    try {
+      if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+        document.addEventListener('visibilitychange', () => {
+          this.heartbeat.reset(Date.now());
+          this.frameBudget.reset();
+        });
+      }
+    } catch { /* no document (worker/test) */ }
+
     // Track startup milestones
     this._startup.milestones.push({ label: 'agent:install', deltaMs: Math.round(this.now() - this._startup.t0) });
   }
 
+  /**
+   * Whether the long tasks seen *recently* warrant an anomaly.
+   *
+   * The old test also added `vitals.longTasks.length` — a cumulative buffer that is
+   * capped at 200 but never decays. Once a page had emitted 10 long tasks in its
+   * lifetime (trivial for any real app) the threshold was permanently satisfied, so
+   * EVERY subsequent long task captured an anomaly and ran a 1s self-profile. That
+   * is a runaway loop: profiling generates long tasks, which schedule more profiling.
+   *
+   * Only `this.longTasks` is consulted — it prunes to a trailing 10s window. `vitals`
+   * stays in the signature because its entries are stamped with a different clock
+   * (`deps.now()`), so they cannot be windowed against this one.
+   */
+  private longTaskAnomalyDue(_vitals: import('../protocol.js').WebVitals): boolean {
+    if (isHidden()) return false;
+    return this.longTasks.count >= LONG_TASK_WINDOW_COUNT;
+  }
+
   /** Mark a startup milestone (call from outside). */
   mark(label: string): void {
     this._startup.milestones.push({
@@ -300,13 +387,23 @@ export class PerfAgent {
   async captureAnomaly(trigger: PerfSnapshot['trigger']): Promise<void> {
     if (this.pendingAnomalies.length >= MAX_PENDING_ANOMALIES) return;
     if (this.profiling && trigger !== 'page-unload') return;
+    // A hidden page's detectors measure browser throttling, not the page. `page-unload`
+    // is exempt: a tab is often hidden at the moment it is torn down.
+    if (trigger !== 'page-unload' && isHidden()) return;
 
     this.profiling = true;
     const heap = heapMb();
     const vitals = this.vitalsReader();
 
+    // The profile is the expensive part (~250 stack captures over 1s). Snapshot every
+    // anomaly, but sample at most once per cooldown so the agent can't become the
+    // dominant cost on a page that is emitting anomalies continuously.
+    const nowMs = Date.now();
+    const mayProfile = trigger !== 'page-unload' && nowMs - this.lastProfileAt >= PROFILE_COOLDOWN_MS;
+
     let callTree: PerfSnapshot['callTree'] = null;
-    if (trigger !== 'page-unload') {
+    if (mayProfile) {
+      this.lastProfileAt = nowMs;
       try {
         const profile = await selfProfile(PROFILE_DURATION_MS, this.now);
         // Flatten the top 10 self-time frames
@@ -326,13 +423,20 @@ export class PerfAgent {
         walk(profile.root);
         frames.sort((a, b) => b.selfMs - a.selfMs);
         const totalSelf = frames.reduce((s, f) => s + f.selfMs, 0);
-        callTree = frames.slice(0, 10).map((f) => ({
-          functionName: f.fn,
-          url: f.url,
-          line: f.line,
-          col: f.col,
-          selfPercent: totalSelf > 0 ? Math.round((f.selfMs / totalSelf) * 100) : 0,
-        }));
+        // No page frames sampled. This is the common case for a single synchronous
+        // block: the sampler runs on a timer, and timers do not run *during* the
+        // block, so by the time it profiles, the page is idle again. Report `null`
+        // rather than an empty tree — an empty array reads as "profiled, nothing hot",
+        // which is a different (and misleading) claim.
+        callTree = frames.length === 0
+          ? null
+          : frames.slice(0, 10).map((f) => ({
+              functionName: f.fn,
+              url: f.url,
+              line: f.line,
+              col: f.col,
+              selfPercent: totalSelf > 0 ? Math.round((f.selfMs / totalSelf) * 100) : 0,
+            }));
       } catch {
         callTree = null;
       }

package/src/inspect/agent/perfAgentThrottle.test.ts

@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { PerfAgent } from './perfAgent.js';
+import type { WebVitals } from '../protocol.js';
+
+const NO_VITALS: WebVitals = { longTasks: [] } as unknown as WebVitals;
+
+function makeAgent(vitals: () => WebVitals = () => NO_VITALS): PerfAgent {
+  let t = 0;
+  return new PerfAgent(() => (t += 1), vitals);
+}
+
+/** Present a `document` with the given visibility to the agent's `isHidden()`. */
+function setHidden(hidden: boolean): void {
+  vi.stubGlobal('document', {
+    hidden,
+    getElementsByTagName: () => [],
+    addEventListener: () => {},
+  });
+}
+
+function heartbeatOf(agent: PerfAgent): { tick(now: number): boolean; reset(now: number): void } {
+  return (agent as unknown as { heartbeat: { tick(now: number): boolean; reset(now: number): void } }).heartbeat;
+}
+
+/** Drive the heartbeat with ticks `gapMs` apart. */
+function drive(agent: PerfAgent, gapMs: number, ticks: number): void {
+  const hb = heartbeatOf(agent);
+  let now = 0;
+  for (let i = 0; i < ticks; i++) {
+    now += gapMs;
+    hb.tick(now);
+  }
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('hidden-tab timer throttling must not read as CPU pressure', () => {
+  it('a hidden page clamped to 1 tick/min is not "under pressure"', () => {
+    setHidden(true);
+    const agent = makeAgent();
+    // Chromium intensive throttling. The page is IDLE — it just is not on screen.
+    // Production showed this converging on ~60000ms of reported "lag".
+    drive(agent, 60_000, 60);
+    const v = agent.vitals();
+    expect(v.eventLoopLagMs).toBeLessThan(1000);
+    expect(v.cpuPressure).toBeLessThan(0.5);
+    expect(v.pendingAnomalies).toEqual([]);
+  });
+
+  it('a hidden page clamped to 1s is not "under pressure" either', () => {
+    setHidden(true);
+    const agent = makeAgent();
+    drive(agent, 1000, 60);
+    expect(agent.vitals().cpuPressure).toBeLessThan(0.5);
+  });
+
+  it('does not charge the page for the hidden→visible gap', () => {
+    setHidden(true);
+    const agent = makeAgent();
+    drive(agent, 60_000, 5);
+    // Becomes visible; the next tick lands a minute after the last throttled one.
+    setHidden(false);
+    const hb = heartbeatOf(agent);
+    const anomaly = hb.tick(300_000 + 60_000);
+    expect(anomaly).toBe(false);
+    expect(agent.vitals().cpuPressure).toBeLessThan(0.5);
+  });
+
+  it('still detects a REAL stall on a visible page', () => {
+    setHidden(false);
+    const agent = makeAgent();
+    const hb = heartbeatOf(agent);
+    let now = 0;
+    for (let i = 0; i < 20; i++) { now += 200; hb.tick(now); }
+    now += 3000; // a genuine 3s synchronous block
+    expect(hb.tick(now)).toBe(true);
+  });
+});
+
+describe('long-task anomaly uses a decaying window', () => {
+  function longTaskDue(agent: PerfAgent, vitals: WebVitals): boolean {
+    return (agent as unknown as { longTaskAnomalyDue(v: WebVitals): boolean })
+      .longTaskAnomalyDue.call(agent, vitals);
+  }
+  function addLongTasks(agent: PerfAgent, n: number): void {
+    const c = (agent as unknown as { longTasks: { add(ts: number, dur: number): void } }).longTasks;
+    for (let i = 0; i < n; i++) c.add(Date.now(), 60);
+  }
+
+  it('ignores the never-decaying cumulative vitals buffer', () => {
+    setHidden(false);
+    // 12 long tasks emitted long ago. Previously `vitals.longTasks.length >= 10` made
+    // the threshold permanently true, so every later long task ran a 1s self-profile.
+    const stale: WebVitals = {
+      longTasks: Array.from({ length: 12 }, () => ({ ts: 0, durationMs: 60 })),
+    } as unknown as WebVitals;
+    const agent = makeAgent(() => stale);
+    expect(longTaskDue(agent, stale)).toBe(false);
+  });
+
+  it('fires on a real burst inside the trailing window', () => {
+    setHidden(false);
+    const agent = makeAgent();
+    addLongTasks(agent, 5);
+    expect(longTaskDue(agent, NO_VITALS)).toBe(true);
+  });
+
+  it('never fires while hidden', () => {
+    setHidden(true);
+    const agent = makeAgent();
+    addLongTasks(agent, 20);
+    expect(longTaskDue(agent, NO_VITALS)).toBe(false);
+  });
+});
+
+describe('self-profile is rate limited', () => {
+  it('captures every anomaly but only profiles once per cooldown', async () => {
+    setHidden(false);
+    const agent = makeAgent();
+
+    await agent.captureAnomaly('cpu-pressure');
+    await agent.captureAnomaly('cpu-pressure');
+    await agent.captureAnomaly('cpu-pressure');
+
+    const trees: (unknown | null)[] = [];
+    for (;;) {
+      const s = agent.takeSnapshot();
+      if (!s) break;
+      trees.push(s.callTree);
+    }
+    expect(trees.length).toBe(3); // every anomaly is still recorded
+    expect(trees.filter((t) => t !== null).length).toBe(1); // only one profile
+  });
+
+  it('does not capture an anomaly at all while hidden', async () => {
+    setHidden(true);
+    const agent = makeAgent();
+    await agent.captureAnomaly('cpu-pressure');
+    expect(agent.takeSnapshot()).toBeNull();
+  });
+
+  it('always captures page-unload, even hidden', async () => {
+    setHidden(true);
+    const agent = makeAgent();
+    await agent.captureAnomaly('page-unload');
+    expect(agent.takeSnapshot()).not.toBeNull();
+  });
+});

package/src/inspect/agent/profile.ts

@@ -37,11 +37,26 @@ function schedule(fn: () => void): void {
   else fn();
 }
 
+/**
+ * Frames belonging to the inspect agent itself. The `profile.(js|ts)` test only ever
+ * matched an unbundled dev build: in the shipped IIFE every module collapses into one
+ * file, so the sampler's own frames survived the filter and it profiled ITSELF —
+ * production call trees were a single minified frame with 100% self time, useless for
+ * finding the real hot path. The bundle now carries a `sourceURL` footer so its frames
+ * are attributable.
+ *
+ * Bare `<anonymous>` is deliberately NOT filtered: page code run through `eval` /
+ * `executeJavaScript` reports that way and is exactly what we want to surface.
+ */
+function isAgentFrame(url: string): boolean {
+  return /profile\.(js|ts)/.test(url) || /ugly-inspect-agent/.test(url);
+}
+
 function captureFrames(): SourceLoc[] {
   // Frames are leaf→root; reverse to root→leaf and drop our own profiler frames.
   const frames = parseStack(new Error().stack, 1);
   return frames
-    .filter((f) => !/profile\.(js|ts)/.test(f.url))
+    .filter((f) => !isAgentFrame(f.url))
     .map((f) => ({ url: f.url, line: f.line, col: f.col, functionName: f.functionName }))
     .reverse();
 }