react-os-shell 4.1.4 → 4.2.0

package/dist/index.d.ts

@@ -2153,6 +2153,169 @@ 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.
+ *
+ * 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 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.
+ */
+declare function summariseLog(log: PerfLogRecord[]): LogSummary;
+/** Flat CSV, for opening in a spreadsheet without writing any code. */
+declare function toCsv(log: PerfLogRecord[]): string;
+
 /**
  * Semantic role of a column, used to auto-map CSV columns to fields and to
  * format the per-column totals. The first column is always the merge "key"
@@ -2731,4 +2894,4 @@ declare function useNewHotkey(callback: () => void): void;
  */
 declare function useEditHotkey(callback: (() => void) | null): void;
 
-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, Banner, type BannerProps, type BannerTone, BarChart, type BarChartProps, BehaviorPanel, 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, 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, Label, type LabelProps, Layout, type LayoutProps, ListFooter, ListLoadError, type ListLoadErrorProps, LoadingSpinner, type LoadingSpinnerProps, 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, PopupMenu, PopupMenuDivider, PopupMenuItem, PopupMenuLabel, Radio, type RadioProps, ResizableTable, SHIFT, 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, VERSION, WidgetManager, WindowCrashedFallback, WindowErrorBoundary, WindowManagerProvider, WindowRegistry, WindowTitle, applyDevTitle, commitExposeHighlight, confirm, confirmDestructive, createWindowRegistry, exitExposeMode, findDuplicateKeys, formatDate, getActiveWindowRoute, getExposeHighlight, getWindowPosition, glassStyle, inputClasses, isDevEnv, isMac, isSeverityTone, mediaFileName, mergeBulkItems, prompt, registerModalEscapeInterceptor, setExposeHighlight, setShellApiClient, setShellAuthBridge, setShellNavIcons, setShellTodoProvider, setWindowDefaultPosition, setWindowPosition, severityOf, subscribeExposeHighlight, toISODate, toast, toggleExposeMode, useClickOutside, useColumnConfig, useDesktopHost, useEditHotkey, useFilters, useInfiniteScroll, useLocalStoragePrefs, useModalActive, useNewHotkey, useShellAuth, useShellEntityFetcher, useShellPrefs, useSort, useTableNav, useWidgetSettings, useWindowManager, useWindowMenuItem, useWindowTitle };
+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, 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, useLocalStoragePrefs, useModalActive, useNewHotkey, useShellAuth, useShellEntityFetcher, useShellPrefs, useSort, useTableNav, useWidgetSettings, useWindowManager, useWindowMenuItem, useWindowTitle };