react-os-shell 4.3.1 → 4.5.0

package/dist/index.d.ts

@@ -881,6 +881,377 @@ declare function WindowManagerProvider({ children, windowAccentForRoute }: {
     windowAccentForRoute?: (route: string) => string | undefined;
 }): react_jsx_runtime.JSX.Element;
 
+/**
+ * Frame-timing maths + bottleneck attribution for the desktop perf HUD.
+ *
+ * Split out from `PerfStats.tsx` because the interesting part is the
+ * *attribution*, and attribution is pure: given a frame rate and how much of
+ * the wall clock the main thread spent blocked, decide whether a janky UI is
+ * the GPU's fault or JavaScript's. That decision is what the HUD exists for —
+ * "the UI feels laggy" is not actionable, "you are GPU-bound" is — so it lives
+ * where a test can pin it.
+ *
+ * The discriminator: frames are landing late, but the main thread is idle.
+ * If JS were the problem the main thread would be busy, so late frames plus an
+ * idle thread means the cost is downstream of script — compositing, paint,
+ * backdrop-filter. The shell leans hard on frosted glass (`utils/glass.ts`
+ * blurs at a 40px radius), which is exactly the kind of work that shows up
+ * here and nowhere in a JS profile.
+ */
+/** Frame rate at or above which we call the UI smooth. Below 60 because
+ *  rAF sampling is noisy and a display may be capped at 60Hz anyway — a
+ *  steady 55 is not a complaint anyone would file. */
+declare const SMOOTH_FPS = 50;
+/** Share of wall-clock time in long tasks that makes JS the prime suspect.
+ *  `longtask` entries are >50ms by definition, so even 20% means the thread
+ *  is stalling several times a second — visible as jank on its own. */
+declare const BLOCKED_PCT_CPU = 20;
+type BottleneckKind = 'smooth' | 'gpu' | 'cpu' | 'unknown';
+interface PerfReading {
+    /** Frames per second across the sample window. */
+    fps: number;
+    /** Mean frame interval, ms. */
+    frameMs: number;
+    /** Slowest single frame in the window, ms — where the jank actually lives. */
+    worstMs: number;
+    /** Percentage of wall-clock time the main thread spent inside long tasks
+     *  (0–100), or null when the browser exposes no `longtask` observer.
+     *  Null is load-bearing: without it we cannot separate GPU from CPU, and
+     *  guessing would defeat the point of the HUD. */
+    blockedPct: number | null;
+}
+interface Verdict {
+    kind: BottleneckKind;
+    /** Headline, for the HUD's verdict row. */
+    label: string;
+    /** One line of what to do about it. */
+    detail: string;
+}
+/** Turn a window of rAF timestamps into a frame-rate reading.
+ *  Needs two timestamps to describe one interval; anything less is not yet a
+ *  measurement and reports zeroes rather than a fabricated 0 fps. */
+declare function summariseFrames(timestamps: number[]): Pick<PerfReading, 'fps' | 'frameMs' | 'worstMs'>;
+/**
+ * Attribute a reading to a bottleneck.
+ *
+ * Order matters: smooth wins outright (nobody cares what a healthy frame rate
+ * is *not* bound by), and an unknown block share can only ever downgrade to
+ * `unknown` — never to `gpu`. Blaming the GPU because the browser withheld
+ * long-task timing would be a confident wrong answer, which is worse than no
+ * answer when someone is about to go change settings on the strength of it.
+ */
+declare function classify(reading: PerfReading): Verdict;
+
+/**
+ * Session log for the desktop perf HUD — and the analysis that turns it into
+ * a conclusion.
+ *
+ * A live frame rate tells you the UI is slow *now*. It does not tell you what
+ * made it slow, and the person watching it is usually the last person able to
+ * say. So while the HUD is on, every reading is stamped with what was
+ * happening around it: how many windows were open, which one was on top,
+ * whether the user was clicking, typing, scrolling or dragging. The log is
+ * exportable, so a laggy machine somewhere else can produce evidence rather
+ * than an adjective.
+ *
+ * The maths here is deliberately non-clever. Median rather than mean, because
+ * one 400ms stall would drag a mean somewhere no frame ever was. Buckets
+ * rather than a fitted curve, because "6 windows open halves the frame rate"
+ * is a sentence someone can act on and a correlation coefficient is not.
+ */
+
+/** One flush interval's worth of measurement plus its context. Keys are short
+ *  because thousands of these get JSON-serialised into localStorage and into
+ *  whatever the user sends afterwards. */
+interface PerfLogRecord {
+    /** Milliseconds since logging began. */
+    t: number;
+    fps: number;
+    frameMs: number;
+    worstMs: number;
+    blockedPct: number | null;
+    heapMB: number | null;
+    verdict: BottleneckKind;
+    /** Open shell windows at the moment of the reading. */
+    windows: number;
+    /** Identity of the topmost window, when there is one — so a summary can name
+     *  the screen that was slow rather than just the count. */
+    active: string | null;
+    clicks: number;
+    keys: number;
+    scrolls: number;
+    /** Milliseconds spent with the pointer down and moving. Dragging is the
+     *  single most compositing-heavy thing a user does in a window shell, so it
+     *  gets its own axis rather than being lumped in with clicks. Covers any
+     *  drag — a window gesture, a desktop icon, a text selection; `moveMs` and
+     *  `resizeMs` below are the window subset of it. */
+    dragMs: number;
+    /** Start-menu opens (`perfEvents`). */
+    menus: number;
+    /** Flyout opens — 2nd- and 3rd-level menus. Hover-opened flyouts fire no
+     *  click and no keypress, so before this axis existed the frame a submenu
+     *  painted on was filed as *idle*, which is where the jank people actually
+     *  report was going missing. */
+    submenus: number;
+    /** Last menu or flyout opened in the interval, so one can be named. */
+    menuKey: string | null;
+    /** Milliseconds spent dragging a window by its title bar. */
+    moveMs: number;
+    /** Milliseconds spent dragging a window's resize handle. */
+    resizeMs: number;
+}
+interface FpsGroup {
+    samples: number;
+    /** Median across the group's *measurable* samples — see `summariseLog`. Zero
+     *  when every sample in the group stalled. */
+    medianFps: number;
+    /** Slowest single frame anywhere in the group. For a group of brief
+     *  interactions this is the number that matters: a flyout that costs one
+     *  300ms frame barely moves a median but is exactly what the user saw. */
+    worstMs: number;
+    /** Samples too blocked to report a frame rate at all. Kept beside the median
+     *  rather than folded into it, so a group that is entirely stalls reads as
+     *  the emergency it is instead of as a 0 fps reading. */
+    stalls: number;
+}
+/**
+ * What the user was doing during a sample, reduced to one label.
+ *
+ * A single interval routinely carries several axes at once — opening a flyout
+ * involves a click, a pointer move and a menu mark — so the ranking below
+ * decides which one the sample is filed under. It runs most-specific first:
+ * the deliberate, expensive gesture beats the incidental click that came with
+ * it, because filing a janky submenu open under "click" is how you end up
+ * optimising the wrong thing.
+ */
+type ActivityKind = 'submenu' | 'menu' | 'resize' | 'move' | 'scroll' | 'type' | 'click' | 'idle';
+/** File a sample under the one thing most likely to have cost it. */
+declare function classifyActivity(r: PerfLogRecord): ActivityKind;
+interface LogSummary {
+    samples: number;
+    durationMs: number;
+    medianFps: number;
+    worstFrameMs: number;
+    /** Fraction of samples in each verdict, 0–1. */
+    verdictShare: Record<BottleneckKind, number>;
+    /** Split by whether the user was doing anything. The gap between these two
+     *  is the headline: a desktop that is smooth at rest and janky in use has a
+     *  rendering cost that only shows up under interaction. */
+    interacting: FpsGroup | null;
+    idle: FpsGroup | null;
+    /** Frame rate per kind of interaction, worst-first — the answer to "which
+     *  gesture is slow", which is the question a report is usually filed to
+     *  ask. */
+    byActivity: (FpsGroup & {
+        kind: ActivityKind;
+    })[];
+    /** Frame rate against how many windows were open. */
+    byWindowCount: (FpsGroup & {
+        windows: number;
+    })[];
+    /** Windows ranked worst-first, so the slowest screen names itself. */
+    worstWindows: (FpsGroup & {
+        key: string;
+    })[];
+    /** Menus and flyouts ranked worst-first, same idea one layer up. */
+    worstMenus: (FpsGroup & {
+        key: string;
+    })[];
+}
+/** Records kept in memory before the oldest are dropped. At one record per
+ *  500ms this is about 20 minutes — long enough to catch an intermittent
+ *  stall, small enough to serialise without thinking about it. */
+declare const LOG_CAP = 2400;
+/** Minimum samples before a group is reported. One unlucky reading is not a
+ *  finding, and a summary that names a window off a single sample invites
+ *  someone to go optimise the wrong screen. */
+declare const MIN_GROUP_SAMPLES = 4;
+/** The floor for menu and gesture groups. Lower because these events are rare
+ *  by construction — a flyout opens inside a single 500ms interval, not across
+ *  twenty of them, so holding them to the window floor would suppress exactly
+ *  the findings the axes were added for. Two still rules out a one-off, and
+ *  every group carries its own `samples` for whoever reads it. */
+declare const MIN_EVENT_SAMPLES = 2;
+/** Append with a cap, oldest dropped first. Returns a new array — callers hold
+ *  this in React state, where mutation would not re-render. */
+declare function appendRecord(log: PerfLogRecord[], record: PerfLogRecord, cap?: number): PerfLogRecord[];
+/** True when the user was doing something during the interval. */
+declare function isInteracting(r: PerfLogRecord): boolean;
+/** Reduce a log to the handful of statements worth acting on. */
+declare function summariseLog(log: PerfLogRecord[]): LogSummary;
+/** Flat CSV, for opening in a spreadsheet without writing any code. */
+declare function toCsv(log: PerfLogRecord[]): string;
+
+/**
+ * What machine the readings came off.
+ *
+ * A frame rate without a machine attached is half a report. "GPU-bound
+ * (compositing)" means something very different on an Intel UHD 620 driving a
+ * 4K panel than on an M3 Max, and the first question anyone triaging a
+ * slowdown asks is which one they are looking at — a question the reporter is
+ * usually the worst-placed person to answer, and often simply cannot.
+ *
+ * The user agent alone does not settle it. Chromium freezes its UA string, so
+ * Windows 11 reports itself as Windows 10 and an ARM machine looks like an x86
+ * one; and no UA string has ever named the GPU, which is the part that matters
+ * most here. So this reads the specifics directly, from four sources:
+ *
+ *   - **Synchronous navigator and screen fields** — cores, memory, panel,
+ *     network, display settings. Cheap, and occasionally withheld.
+ *   - **A WebGL context**, purely to ask the driver its own name. Created and
+ *     destroyed inside one call, at report time and never during measurement,
+ *     because a live context is exactly the sort of thing that would show up in
+ *     the numbers it is meant to explain.
+ *   - **Client hints and the battery**, both async, both unchanging, so both
+ *     are resolved once when the HUD mounts rather than while a report is being
+ *     assembled.
+ *   - **Media queries**, for the settings that change how much compositing the
+ *     browser is being asked to do in the first place.
+ *
+ * Everything is best-effort and every field degrades to null. Firefox and
+ * Safari withhold `deviceMemory`; Safari has no client hints; a blocklisted
+ * driver refuses WebGL. A report missing one line is a far smaller loss than a
+ * report that failed to send, so nothing here is allowed to throw.
+ */
+/** Async platform detail from `navigator.userAgentData`. */
+interface PlatformHints {
+    /** 'macOS', 'Windows', 'Linux', … */
+    platform: string | null;
+    /** The real OS version, which the frozen UA string no longer carries. */
+    platformVersion: string | null;
+    /** 'arm' | 'x86' — an Intel Mac and an Apple Silicon Mac are not the same
+     *  machine and do not have the same compositing story. */
+    architecture: string | null;
+    /** Device model, on mobile. */
+    model: string | null;
+    /** Browser name and full version, e.g. 'Chrome 141.0.7390.55'. */
+    browser: string | null;
+}
+/** Power state. A laptop in Low Power Mode is capped at 30 fps by the OS, which
+ *  is the single most common cause of "it halved this afternoon". */
+interface BatteryInfo {
+    charging: boolean;
+    /** 0–1. */
+    level: number;
+}
+/** The parts that cannot be read synchronously, resolved once on mount. */
+interface AsyncEnvironment {
+    hints: PlatformHints | null;
+    battery: BatteryInfo | null;
+}
+interface PerfEnvironment {
+    userAgent: string;
+    /** Browser name and version from client hints; null outside Chromium, where
+     *  `userAgent` above is the fallback. */
+    browser: string | null;
+    platform: string | null;
+    platformVersion: string | null;
+    architecture: string | null;
+    model: string | null;
+    /** Logical cores. The shell is single-threaded, so this mostly says how much
+     *  else the machine can be doing at once. */
+    cpuCores: number | null;
+    /** Approximate RAM in GB. Deliberately coarse — the spec has browsers round
+     *  to a power of two and permits clamping to 8 to blunt fingerprinting, so
+     *  treat it as a floor ("this much or more"), not a measurement. Chromium
+     *  only; Firefox and Safari publish nothing. */
+    deviceMemoryGB: number | null;
+    /** The driver's own name for itself, e.g. 'Apple M3 Max' or
+     *  'ANGLE (Intel, Intel(R) UHD Graphics 620 …)'. */
+    gpu: string | null;
+    gpuVendor: string | null;
+    /** False when the browser fell back to software rendering — which explains a
+     *  GPU-bound verdict outright. */
+    webglAvailable: boolean;
+    screen: {
+        width: number;
+        height: number;
+        dpr: number;
+        colorDepth: number | null;
+    };
+    /** The window, which is what actually gets composited — a maximised window on
+     *  a 4K panel and a small one are different amounts of work. */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Heap ceiling this tab was given, MB. Chromium only. */
+    heapLimitMB: number | null;
+    /** Effective connection class, downlink Mb/s and round-trip ms. Separates a
+     *  UI that is slow from a UI that is waiting. */
+    network: {
+        effectiveType: string | null;
+        downlinkMbps: number | null;
+        rttMs: number | null;
+        saveData: boolean;
+    } | null;
+    battery: BatteryInfo | null;
+    /** Settings that change how much work the browser is being asked to do. */
+    prefersReducedMotion: boolean;
+    forcedColors: boolean;
+    /** The shell's own "reduce transparency" — the first thing to suggest, and
+     *  the first thing to check has not already been tried. */
+    reducedTransparency: boolean;
+    /** Screens can be scaled; a report from a 4K panel at 200% is not the same as
+     *  one at 100%. */
+    touchPoints: number | null;
+}
+/**
+ * Resolve everything that needs a promise. Call once, keep the result — the
+ * values cannot change for the life of the page, and the prompt some browsers
+ * attach to high-entropy hints must not fire while someone is filing a report.
+ *
+ * Never rejects. A browser with no client hints and no battery API is the
+ * normal case outside Chromium, not an error worth handling at the call site.
+ */
+declare function requestAsyncEnvironment(): Promise<AsyncEnvironment>;
+/** Snapshot the machine. Synchronous — pass what `requestAsyncEnvironment`
+ *  resolved earlier, or null if it never arrived. */
+declare function readEnvironment(async_: AsyncEnvironment | null): PerfEnvironment;
+/**
+ * One line naming the machine, for a report title or a bug-tracker
+ * description — the place where a reader decides whether this report is about
+ * a slow machine or a slow application. The full record is in the attachment;
+ * this is the digest.
+ *
+ * Omits what it does not know rather than printing "unknown": a line of
+ * absences reads as a broken probe, when in truth Firefox simply does not
+ * publish RAM.
+ */
+declare function describeMachine(env: PerfEnvironment): string;
+
+/** A finished report, handed to the host to file. The JSON is pre-serialised
+ *  because the host's job is to attach it, not to re-derive it; `summary` and
+ *  `verdict` come along so a host can title or route the report without
+ *  parsing the attachment back apart. */
+interface PerfReport {
+    /** What the user typed about what they were doing. May be empty. */
+    message: string;
+    /** Suggested attachment filename, stamped with the local time. */
+    filename: string;
+    /** The whole report — environment, summary and every raw record. */
+    json: string;
+    summary: LogSummary;
+    /** The HUD's current headline, e.g. "GPU-bound (compositing)". */
+    verdict: string;
+    /** The machine the readings came off — GPU, cores, memory, OS, screen. A
+     *  verdict of "GPU-bound" is not actionable until you know which GPU. */
+    environment: PerfEnvironment;
+}
+interface PerfStatsProps {
+    /** Dismiss handler — the shell wires this to turn the pref back off, so the
+     *  HUD can be closed from itself rather than only from Preferences. */
+    onClose?: () => void;
+    /** File the report through the host's own feedback channel — the whole point
+     *  of the HUD, since a log that reaches nobody fixes nothing. Rejecting
+     *  surfaces the error and keeps the composer open with the text intact.
+     *  Without it the button downloads the same JSON instead, so the shell stays
+     *  usable standalone. */
+    onSubmit?: (report: PerfReport) => void | Promise<void>;
+    className?: string;
+}
+declare function PerfStats({ onClose, onSubmit, className }: PerfStatsProps): react_jsx_runtime.JSX.Element;
+
 /**
  * INTERNAL stub — Desktop's About modal references the consumer-side
  * changelog. The package ships no built-in changelog; consumer wires their
@@ -969,6 +1340,12 @@ interface DesktopHostConfig {
      *  calls this. Lets a consumer that files feedback natively (the shell itself
      *  dropped bug reporting in v3.0.0) surface the familiar right-click entry. */
     onReportBug?: () => void;
+    /** File a performance report from the desktop perf HUD through the same
+     *  feedback channel, with the session log attached. Unset, the HUD's button
+     *  downloads the report instead — which is a strictly worse outcome, because
+     *  a file on someone's Downloads folder is not a bug report. Rejecting shows
+     *  the error in the HUD and keeps what the user typed. */
+    onSubmitPerfReport?: (report: PerfReport) => void | Promise<void>;
 }
 declare function DesktopHostProvider({ value, children }: {
     value: DesktopHostConfig;
@@ -2178,168 +2555,47 @@ interface MetricBarProps {
 }
 declare function MetricBar({ label, value, max, warn, crit, severity, detail, formatValue, emptyLabel, size, ariaLabel, className, }: MetricBarProps): react_jsx_runtime.JSX.Element;
 
-interface PerfStatsProps {
-    /** Dismiss handler — the shell wires this to turn the pref back off, so the
-     *  HUD can be closed from itself rather than only from Preferences. */
-    onClose?: () => void;
-    className?: string;
-}
-declare function PerfStats({ onClose, className }: PerfStatsProps): react_jsx_runtime.JSX.Element;
-
 /**
- * Frame-timing maths + bottleneck attribution for the desktop perf HUD.
+ * Shell interaction marks, folded into every perf-log record.
  *
- * Split out from `PerfStats.tsx` because the interesting part is the
- * *attribution*, and attribution is pure: given a frame rate and how much of
- * the wall clock the main thread spent blocked, decide whether a janky UI is
- * the GPU's fault or JavaScript's. That decision is what the HUD exists for —
- * "the UI feels laggy" is not actionable, "you are GPU-bound" is — so it lives
- * where a test can pin it.
+ * The HUD can see that frames were dropped and it can see that the pointer
+ * moved, but "the pointer moved" covers wandering across the desktop and
+ * opening a third-level flyout, and only one of those repaints a frosted
+ * surface. The first version of the log conflated them, so the readings that
+ * mattered most — the frame the start menu opened on, the frame a window was
+ * dragged across — arrived indistinguishable from an idle mouse. A report full
+ * of anonymous samples points at nothing.
  *
- * The discriminator: frames are landing late, but the main thread is idle.
- * If JS were the problem the main thread would be busy, so late frames plus an
- * idle thread means the cost is downstream of script — compositing, paint,
- * backdrop-filter. The shell leans hard on frosted glass (`utils/glass.ts`
- * blurs at a 40px radius), which is exactly the kind of work that shows up
- * here and nowhere in a JS profile.
- */
-/** Frame rate at or above which we call the UI smooth. Below 60 because
- *  rAF sampling is noisy and a display may be capped at 60Hz anyway — a
- *  steady 55 is not a complaint anyone would file. */
-declare const SMOOTH_FPS = 50;
-/** Share of wall-clock time in long tasks that makes JS the prime suspect.
- *  `longtask` entries are >50ms by definition, so even 20% means the thread
- *  is stalling several times a second — visible as jank on its own. */
-declare const BLOCKED_PCT_CPU = 20;
-type BottleneckKind = 'smooth' | 'gpu' | 'cpu' | 'unknown';
-interface PerfReading {
-    /** Frames per second across the sample window. */
-    fps: number;
-    /** Mean frame interval, ms. */
-    frameMs: number;
-    /** Slowest single frame in the window, ms — where the jank actually lives. */
-    worstMs: number;
-    /** Percentage of wall-clock time the main thread spent inside long tasks
-     *  (0–100), or null when the browser exposes no `longtask` observer.
-     *  Null is load-bearing: without it we cannot separate GPU from CPU, and
-     *  guessing would defeat the point of the HUD. */
-    blockedPct: number | null;
-}
-interface Verdict {
-    kind: BottleneckKind;
-    /** Headline, for the HUD's verdict row. */
-    label: string;
-    /** One line of what to do about it. */
-    detail: string;
-}
-/** Turn a window of rAF timestamps into a frame-rate reading.
- *  Needs two timestamps to describe one interval; anything less is not yet a
- *  measurement and reports zeroes rather than a fabricated 0 fps. */
-declare function summariseFrames(timestamps: number[]): Pick<PerfReading, 'fps' | 'frameMs' | 'worstMs'>;
-/**
- * Attribute a reading to a bottleneck.
+ * So the places that do the expensive things say so. Menus mark themselves when
+ * they open; window drags and resizes mark themselves for as long as they run.
+ * Everything here is a plain counter drained once per flush interval — no
+ * subscriptions, no allocation per event, nothing that would make marking an
+ * event cost more than the event.
  *
- * Order matters: smooth wins outright (nobody cares what a healthy frame rate
- * is *not* bound by), and an unknown block share can only ever downgrade to
- * `unknown` — never to `gpu`. Blaming the GPU because the browser withheld
- * long-task timing would be a confident wrong answer, which is worse than no
- * answer when someone is about to go change settings on the strength of it.
+ * Marks accumulate only while the HUD is mounted (`setPerfCollecting`). That is
+ * not really about cost — incrementing a number is free — but about honesty: a
+ * counter that had been climbing since page load would attribute a morning's
+ * worth of menu opens to whichever 500ms interval happened to drain it first.
  */
-declare function classify(reading: PerfReading): Verdict;
-
+/** Which menu layer opened. The distinction is the point: the root menu is one
+ *  surface appearing, a flyout is a second one appearing *over* it, and the
+ *  cost of the second is what people report. */
+type MenuLayer = 'menu' | 'submenu';
+/** Record that a menu surface opened. `key` names it (a section label, a route)
+ *  so the summary can rank flyouts against each other. */
+declare function markMenuOpen(layer: MenuLayer, key: string): void;
 /**
- * Session log for the desktop perf HUD — and the analysis that turns it into
- * a conclusion.
+ * Record a window drag or resize for as long as it runs. Returns the end
+ * function; calling it twice adds the span once.
  *
- * A live frame rate tells you the UI is slow *now*. It does not tell you what
- * made it slow, and the person watching it is usually the last person able to
- * say. So while the HUD is on, every reading is stamped with what was
- * happening around it: how many windows were open, which one was on top,
- * whether the user was clicking, typing, scrolling or dragging. The log is
- * exportable, so a laggy machine somewhere else can produce evidence rather
- * than an adjective.
- *
- * The maths here is deliberately non-clever. Median rather than mean, because
- * one 400ms stall would drag a mean somewhere no frame ever was. Buckets
- * rather than a fitted curve, because "6 windows open halves the frame rate"
- * is a sentence someone can act on and a correlation coefficient is not.
- */
-
-/** One flush interval's worth of measurement plus its context. Keys are short
- *  because thousands of these get JSON-serialised into localStorage and into
- *  whatever the user emails afterwards. */
-interface PerfLogRecord {
-    /** Milliseconds since logging began. */
-    t: number;
-    fps: number;
-    frameMs: number;
-    worstMs: number;
-    blockedPct: number | null;
-    heapMB: number | null;
-    verdict: BottleneckKind;
-    /** Open shell windows at the moment of the reading. */
-    windows: number;
-    /** Identity of the topmost window, when there is one — so a summary can name
-     *  the screen that was slow rather than just the count. */
-    active: string | null;
-    clicks: number;
-    keys: number;
-    scrolls: number;
-    /** Milliseconds spent mid-drag during the interval. Dragging is the single
-     *  most compositing-heavy thing a user does in a window shell, so it gets
-     *  its own axis rather than being lumped in with clicks. */
-    dragMs: number;
-}
-interface FpsGroup {
-    samples: number;
-    medianFps: number;
-}
-interface LogSummary {
-    samples: number;
-    durationMs: number;
-    medianFps: number;
-    worstFrameMs: number;
-    /** Fraction of samples in each verdict, 0–1. */
-    verdictShare: Record<BottleneckKind, number>;
-    /** Split by whether the user was doing anything. The gap between these two
-     *  is the headline: a desktop that is smooth at rest and janky in use has a
-     *  rendering cost that only shows up under interaction. */
-    interacting: FpsGroup | null;
-    idle: FpsGroup | null;
-    /** Frame rate against how many windows were open. */
-    byWindowCount: (FpsGroup & {
-        windows: number;
-    })[];
-    /** Windows ranked worst-first, so the slowest screen names itself. */
-    worstWindows: (FpsGroup & {
-        key: string;
-    })[];
-}
-/** Records kept in memory before the oldest are dropped. At one record per
- *  500ms this is about 20 minutes — long enough to catch an intermittent
- *  stall, small enough to serialise without thinking about it. */
-declare const LOG_CAP = 2400;
-/** Minimum samples before a group is reported. One unlucky reading is not a
- *  finding, and a summary that names a window off a single sample invites
- *  someone to go optimise the wrong screen. */
-declare const MIN_GROUP_SAMPLES = 4;
-/** Append with a cap, oldest dropped first. Returns a new array — callers hold
- *  this in React state, where mutation would not re-render. */
-declare function appendRecord(log: PerfLogRecord[], record: PerfLogRecord, cap?: number): PerfLogRecord[];
-/** True when the user was doing something during the interval. */
-declare function isInteracting(r: PerfLogRecord): boolean;
-/**
- * Reduce a log to the handful of statements worth acting on.
- *
- * Only samples with a real frame rate are measured — a reading taken while the
- * main thread was too blocked to deliver frames carries fps 0, and letting
- * those into a median would report a frame rate the display never showed.
- * They still count toward `verdictShare`, which is where that condition
- * belongs.
+ * Duration rather than a count because these are the gestures whose *cost is
+ * their length* — a drag that stutters for four seconds and a drag that lasted
+ * one frame are the same event and very different reports. The span is credited
+ * to the interval it ends in, which can straddle a flush boundary; that is
+ * accepted rather than apportioned, because a drag long enough to straddle two
+ * intervals is already the thing being investigated.
  */
-declare function summariseLog(log: PerfLogRecord[]): LogSummary;
-/** Flat CSV, for opening in a spreadsheet without writing any code. */
-declare function toCsv(log: PerfLogRecord[]): string;
+declare function beginWindowGesture(kind: 'move' | 'resize'): () => void;
 
 /**
  * Semantic role of a column, used to auto-map CSV columns to fields and to
@@ -3116,4 +3372,4 @@ interface UndoState {
     future: UndoStep[];
 }
 
-export { ALT, ALT_SHIFT_D, ALT_SHIFT_E, ALT_SHIFT_N, Accordion, type AccordionItem, type AccordionProps, AuthScreen, type AuthScreenProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, BLOCKED_PCT_CPU, Banner, type BannerProps, type BannerTone, BarChart, type BarChartProps, BehaviorPanel, type BottleneckKind, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, type BulkColumn, type BulkColumnKind, BulkImportGrid, type BulkImportGridProps, type BulkRow, Button, type ButtonProps, type ButtonSize, type ButtonVariant, CMD_A, CMD_DOT, CMD_ENTER, CMD_K, CMD_S, CancelButton, Card, type CardProps, type CellStyle, ChangePasswordForm, type ChangePasswordFormProps, type ChangelogEntry, ChatTemplate, Checkbox, type CheckboxProps, CheckoutTemplate, type ClockCalendarConfig, ColoredBadge, type ColoredBadgeProps, type ColumnDef, ConfirmProvider, ContainerFillChart, type ContainerFillChartProps, type ContainerFillItem, CopyButton, Customization, type CustomizationOmitSection, type CustomizationProps, type CustomizationSection, DEV_BANNER_TEXT, DashboardTemplate, DataTablePage, DateRangePicker, type DateRangePickerProps, Desktop, type DesktopContextMenuItem, type DesktopHostConfig, DesktopHostProvider, DevIndicator, DocFavStar, DonutChart, type DonutChartProps, type DonutSegment, type DuplicateGroup, ENTER, EditableGrid, type EditableGridProps, EmailTemplate, EmptyState, type EmptyStateProps, type EntityFetcher, EntityList, type EntityListColumn, type EntityListContextAction, type EntityListProps, ErrorPage, type ErrorPageProps, FilterBar, type FilterOption, FormField, type FormFieldProps, FormLayoutPage, type FpsGroup, GLASS_DIVIDER, GLASS_INPUT_BG, GalleryTemplate, GlobalSearch, type GridColumn, type HealthCheckResult, HelpCenter, type HelpCenterDoc, type HelpCenterProps, INPUT_BASE, ImageAnnotator, type ImageAnnotatorHandle, type ImageAnnotatorProps, Input, type InputProps, Kanban, type KanbanColumn, type KanbanProps, LOG_CAP, Label, type LabelProps, Layout, type LayoutProps, ListFooter, ListLoadError, type ListLoadErrorProps, LoadingSpinner, type LoadingSpinnerProps, type LogSummary, MIN_GROUP_SAMPLES, MOD, Markdown, type MarkdownProps, MediaUploadField, type MediaUploadFieldProps, MediaUploadGrid, type MediaUploadGridItem, type MediaUploadGridProps, type MergeBulkOptions, type MergeBulkResult, MetricBar, type MetricBarProps, type Milestone, type MilestoneKind, MilestoneTimeline, type MilestoneTimelineProps, type MobileAppConfig, Modal, ModalActions, NativeSelect, NotificationBell, type NotificationsConfig, PageHeader, type PageHeaderProps, type PaginatedResponse, Pagination, type PaginationProps, PdfActionButton, type PdfActionButtonProps, type PerfLogRecord, type PerfReading, PerfStats, type PerfStatsProps, PopupMenu, PopupMenuDivider, PopupMenuItem, PopupMenuLabel, Radio, type RadioProps, ResizableTable, SHIFT, SMOOTH_FPS, type SearchConfig, type SearchProvider, type SearchResult, type SearchableOption, SearchableSelect, type SearchableSelectProps, Select, type SelectOption, type SelectProps, type SemanticGroup, ServerStatusIndicator, type ServerStatusIndicatorProps, type ServerStatusUser, type SeverityTone, type ShellAuth, ShellAuthProvider, ShellEntityFetcherProvider, type ShellNotification, type ShellPrefsAdapter, ShellPrefsProvider, ShortcutHelp, SidebarActionButton, type SidebarActionButtonProps, SidebarGroupLabel, SidebarLayout, type SidebarLayoutProps, SidebarNavItem, type SortState, SoundsPanel, Sparkline, type SparklineProps, StartMenu, StatCard, type StatCardProps, StatusBadge, StatusBadgeProvider, type StickyEntityRef, type StickyResolver, SystemPreferences, type SystemPreferencesProps, type SystemPreferencesSection, type TabItem, Tabs, type TabsProps, Textarea, type TextareaProps, type TodoProvider, type TodoTask, Tooltip, type TooltipProps, TopNav, type TopNavItem, type TopNavProps, UndoControls, type UndoControlsApi, type UndoControlsProps, UndoProvider, type UndoProviderProps, type UndoSnapshot, type UndoState, type UndoStep, type UndoableOptions, VERSION, type Verdict, WidgetManager, WindowCrashedFallback, WindowErrorBoundary, WindowManagerProvider, WindowRegistry, WindowTitle, appendRecord as appendPerfRecord, applyDevTitle, classify as classifyPerf, commitExposeHighlight, confirm, confirmDestructive, createWindowRegistry, exitExposeMode, findDuplicateKeys, formatDate, getActiveWindowRoute, getExposeHighlight, getWindowPosition, glassStyle, inputClasses, isDevEnv, isInteracting, isMac, isSeverityTone, mediaFileName, mergeBulkItems, toCsv as perfLogToCsv, prompt, registerModalEscapeInterceptor, setExposeHighlight, setShellApiClient, setShellAuthBridge, setShellNavIcons, setShellTodoProvider, setWindowDefaultPosition, setWindowPosition, severityOf, subscribeExposeHighlight, summariseFrames, summariseLog as summarisePerfLog, toISODate, toast, toggleExposeMode, useClickOutside, useColumnConfig, useDesktopHost, useEditHotkey, useFilters, useInfiniteScroll, useIsActiveWindow, useLocalStoragePrefs, useModalActive, useNewHotkey, useShellAuth, useShellEntityFetcher, useShellPrefs, useSort, useTableNav, useUndo, useUndoable, useUndoableState, useWidgetSettings, useWindowManager, useWindowMenuItem, useWindowTitle };
+export { ALT, ALT_SHIFT_D, ALT_SHIFT_E, ALT_SHIFT_N, Accordion, type AccordionItem, type AccordionProps, type ActivityKind, type AsyncEnvironment, AuthScreen, type AuthScreenProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, BLOCKED_PCT_CPU, Banner, type BannerProps, type BannerTone, BarChart, type BarChartProps, type BatteryInfo, BehaviorPanel, type BottleneckKind, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, type BulkColumn, type BulkColumnKind, BulkImportGrid, type BulkImportGridProps, type BulkRow, Button, type ButtonProps, type ButtonSize, type ButtonVariant, CMD_A, CMD_DOT, CMD_ENTER, CMD_K, CMD_S, CancelButton, Card, type CardProps, type CellStyle, ChangePasswordForm, type ChangePasswordFormProps, type ChangelogEntry, ChatTemplate, Checkbox, type CheckboxProps, CheckoutTemplate, type ClockCalendarConfig, ColoredBadge, type ColoredBadgeProps, type ColumnDef, ConfirmProvider, ContainerFillChart, type ContainerFillChartProps, type ContainerFillItem, CopyButton, Customization, type CustomizationOmitSection, type CustomizationProps, type CustomizationSection, DEV_BANNER_TEXT, DashboardTemplate, DataTablePage, DateRangePicker, type DateRangePickerProps, Desktop, type DesktopContextMenuItem, type DesktopHostConfig, DesktopHostProvider, DevIndicator, DocFavStar, DonutChart, type DonutChartProps, type DonutSegment, type DuplicateGroup, ENTER, EditableGrid, type EditableGridProps, EmailTemplate, EmptyState, type EmptyStateProps, type EntityFetcher, EntityList, type EntityListColumn, type EntityListContextAction, type EntityListProps, ErrorPage, type ErrorPageProps, FilterBar, type FilterOption, FormField, type FormFieldProps, FormLayoutPage, type FpsGroup, GLASS_DIVIDER, GLASS_INPUT_BG, GalleryTemplate, GlobalSearch, type GridColumn, type HealthCheckResult, HelpCenter, type HelpCenterDoc, type HelpCenterProps, INPUT_BASE, ImageAnnotator, type ImageAnnotatorHandle, type ImageAnnotatorProps, Input, type InputProps, Kanban, type KanbanColumn, type KanbanProps, LOG_CAP, Label, type LabelProps, Layout, type LayoutProps, ListFooter, ListLoadError, type ListLoadErrorProps, LoadingSpinner, type LoadingSpinnerProps, type LogSummary, MIN_EVENT_SAMPLES, MIN_GROUP_SAMPLES, MOD, Markdown, type MarkdownProps, MediaUploadField, type MediaUploadFieldProps, MediaUploadGrid, type MediaUploadGridItem, type MediaUploadGridProps, type MenuLayer, type MergeBulkOptions, type MergeBulkResult, MetricBar, type MetricBarProps, type Milestone, type MilestoneKind, MilestoneTimeline, type MilestoneTimelineProps, type MobileAppConfig, Modal, ModalActions, NativeSelect, NotificationBell, type NotificationsConfig, PageHeader, type PageHeaderProps, type PaginatedResponse, Pagination, type PaginationProps, PdfActionButton, type PdfActionButtonProps, type PerfEnvironment, type PerfLogRecord, type PerfReading, type PerfReport, PerfStats, type PerfStatsProps, type PlatformHints, PopupMenu, PopupMenuDivider, PopupMenuItem, PopupMenuLabel, Radio, type RadioProps, ResizableTable, SHIFT, SMOOTH_FPS, type SearchConfig, type SearchProvider, type SearchResult, type SearchableOption, SearchableSelect, type SearchableSelectProps, Select, type SelectOption, type SelectProps, type SemanticGroup, ServerStatusIndicator, type ServerStatusIndicatorProps, type ServerStatusUser, type SeverityTone, type ShellAuth, ShellAuthProvider, ShellEntityFetcherProvider, type ShellNotification, type ShellPrefsAdapter, ShellPrefsProvider, ShortcutHelp, SidebarActionButton, type SidebarActionButtonProps, SidebarGroupLabel, SidebarLayout, type SidebarLayoutProps, SidebarNavItem, type SortState, SoundsPanel, Sparkline, type SparklineProps, StartMenu, StatCard, type StatCardProps, StatusBadge, StatusBadgeProvider, type StickyEntityRef, type StickyResolver, SystemPreferences, type SystemPreferencesProps, type SystemPreferencesSection, type TabItem, Tabs, type TabsProps, Textarea, type TextareaProps, type TodoProvider, type TodoTask, Tooltip, type TooltipProps, TopNav, type TopNavItem, type TopNavProps, UndoControls, type UndoControlsApi, type UndoControlsProps, UndoProvider, type UndoProviderProps, type UndoSnapshot, type UndoState, type UndoStep, type UndoableOptions, VERSION, type Verdict, WidgetManager, WindowCrashedFallback, WindowErrorBoundary, WindowManagerProvider, WindowRegistry, WindowTitle, appendRecord as appendPerfRecord, applyDevTitle, beginWindowGesture, classifyActivity, classify as classifyPerf, commitExposeHighlight, confirm, confirmDestructive, createWindowRegistry, describeMachine, exitExposeMode, findDuplicateKeys, formatDate, getActiveWindowRoute, getExposeHighlight, getWindowPosition, glassStyle, inputClasses, isDevEnv, isInteracting, isMac, isSeverityTone, markMenuOpen, mediaFileName, mergeBulkItems, toCsv as perfLogToCsv, prompt, readEnvironment as readPerfEnvironment, registerModalEscapeInterceptor, requestAsyncEnvironment, setExposeHighlight, setShellApiClient, setShellAuthBridge, setShellNavIcons, setShellTodoProvider, setWindowDefaultPosition, setWindowPosition, severityOf, subscribeExposeHighlight, summariseFrames, summariseLog as summarisePerfLog, toISODate, toast, toggleExposeMode, useClickOutside, useColumnConfig, useDesktopHost, useEditHotkey, useFilters, useInfiniteScroll, useIsActiveWindow, useLocalStoragePrefs, useModalActive, useNewHotkey, useShellAuth, useShellEntityFetcher, useShellPrefs, useSort, useTableNav, useUndo, useUndoable, useUndoableState, useWidgetSettings, useWindowManager, useWindowMenuItem, useWindowTitle };