react-os-shell 4.2.2 → 4.4.0

package/dist/index.d.ts

@@ -235,6 +235,30 @@ interface ModalProps {
 }
 /** Register an Escape interceptor; returns an unregister function. */
 declare function registerModalEscapeInterceptor(fn: (e: KeyboardEvent) => boolean): () => void;
+/**
+ * Is the window identified by `windowKey` the frontmost one?
+ *
+ * For anything that binds a global shortcut from *outside* the `<Modal>` it
+ * belongs to — `UndoProvider` is mounted a level above `PageWindow`, so it has
+ * no `ModalActionsContext` to read and cannot use {@link useModalActive}, whose
+ * fallback path is made of module globals and therefore answers identically for
+ * every caller. That fallback is fine for "is any window active"; it is useless
+ * for "is *mine* active", and a per-window listener that asks the wrong
+ * question fires in every window at once.
+ *
+ * `windowKey` is the stable key a window passes to `<Modal windowKey=...>` —
+ * `WindowManager`'s `item.id` — not the private per-mount `modalId` that
+ * `activationOrder` actually holds. The two are mapped by `mountModal`, and
+ * resolving through that map is the whole point: `useIsActiveModal(item.id)`
+ * would compare a window key against a `modal-xxxxxx` id and be false for every
+ * window rather than true for every window.
+ *
+ * Omit `windowKey` — or pass one no mounted modal has claimed, which is the
+ * case for a `rendersOwnModal` window whose inner `<Modal>` sets no
+ * `windowKey` — and this degrades to {@link useModalActive}: the enclosing
+ * `<ModalActions>` context if there is one, the global test if there is not.
+ */
+declare function useIsActiveWindow(windowKey?: string | null): boolean;
 declare function toggleExposeMode(): void;
 declare function exitExposeMode(): void;
 declare function subscribeExposeHighlight(fn: () => void): () => boolean;
@@ -857,6 +881,236 @@ 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;
+
+/** 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;
+}
+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
@@ -945,6 +1199,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;
@@ -2154,168 +2414,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.
- *
- * 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.
+ * Shell interaction marks, folded into every perf-log record.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
+ */
+/** 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;
+/**
+ * Record a window drag or resize for as long as it runs. Returns the end
+ * function; calling it twice adds the span once.
  *
- * 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
@@ -2428,6 +2567,23 @@ interface MergeBulkOptions<T extends BaseItem> {
 }
 declare function mergeBulkItems<T extends BaseItem>(options: MergeBulkOptions<T>): MergeBulkResult<T>;
 
+interface UndoControlsProps {
+    /** Extra classes for the wrapping row. */
+    className?: string;
+}
+/**
+ * Undo/Redo for the enclosing form, reading the stack from {@link UndoProvider}.
+ *
+ * Put it wherever the form's actions live — a window header, a section header,
+ * beside the save button. The keys work without it; this is for discoverability
+ * and for the mouse. Both buttons stay rendered and go disabled, so the row
+ * does not reflow the moment there is something to undo.
+ *
+ * Renders nothing for a user who may not edit the record — dead buttons on a
+ * read-only form read as something broken rather than something withheld.
+ */
+declare function UndoControls({ className }: UndoControlsProps): react_jsx_runtime.JSX.Element | null;
+
 /** Default item shape — overridable via the accessor props for any other shape. */
 interface ContainerFillItem {
     quantity?: number | null;
@@ -2895,4 +3051,184 @@ 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, 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 };
+interface UndoProviderProps {
+    children: React.ReactNode;
+    /**
+     * Whether this user may edit the record. Undo is offered to everyone who
+     * can — it is not gated on role or seniority — and withheld from a reader
+     * only because they have nothing to take back. Defaults to true.
+     */
+    canEdit?: boolean;
+    /**
+     * Permission codes that count as "may edit", checked through
+     * `ShellAuthProvider`. Combined with `canEdit`, so a form that already knows
+     * it is read-only stays read-only whatever the codes say. Omit to rely on
+     * `canEdit` alone.
+     */
+    perms?: string[];
+    /**
+     * The window this stack belongs to — the same stable key its `<Modal>` gets
+     * as `windowKey`, which for a `WindowManager` window is `item.id`.
+     *
+     * This is what keeps ⌘Z inside the window the user is looking at. The
+     * provider binds its hotkey on `window`, so every open window's provider sees
+     * every keypress; the id is how one of them recognises the press as its own.
+     * Without it there is no per-window identity to test and the best available
+     * answer is "is any window active", which is true in all of them at once.
+     *
+     * Omit it for a provider nested inside a `<Modal>` — there the enclosing
+     * modal's own context answers the question — or where there are no windows
+     * at all.
+     */
+    windowId?: string;
+}
+/**
+ * Undo/redo for everything in one open form.
+ *
+ * Wrap a form window in it, register each piece of its state with
+ * {@link useUndoable}, and the whole form shares one stack: a field edit, a
+ * line added, a bulk import are all steps in the same history, undone newest
+ * first. Two open windows have two independent stacks, and passing
+ * {@link UndoProviderProps.windowId} is what keeps them independent in
+ * practice — see that prop.
+ *
+ * History is the unsaved edit only. It lives with the mounted provider and
+ * dies with it. Both ends of the edit are the caller's to mark: `baseline()`
+ * once the record has arrived, so the load is the starting point rather than
+ * the first thing ⌘Z takes back, and `clear()` at a save, past which "earlier"
+ * is on the server and not something a form can reach.
+ *
+ * Anyone who may edit the record gets it — it is not a privileged feature, and
+ * the user most helped by an undo is the one least sure of what they just did.
+ * A reader is the only one it is withheld from, and only because there is
+ * nothing for them to take back. Note that `canEdit` is the caller's claim, and
+ * the shell-level provider `WindowManager` mounts around every window has no
+ * way to make it: it knows nothing about the record inside. That one defaults
+ * to enabled, and a read-only form states the fact by nesting its own
+ * `<UndoProvider canEdit={false}>`, which shadows it.
+ */
+declare function UndoProvider({ children, canEdit, perms, windowId }: UndoProviderProps): react_jsx_runtime.JSX.Element;
+interface UndoControlsApi {
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    /** What Undo/Redo would act on, for a button title. Null when unavailable. */
+    undoLabel: string | null;
+    redoLabel: string | null;
+    /** End the history — call after a successful save. */
+    clear: () => void;
+    /**
+     * Make the form as it stands the starting point, discarding the history.
+     *
+     * Call it once the record has arrived from the server. State filled from a
+     * fetch is a change like any other as far as the slices are concerned, so
+     * without this the load itself is the oldest step and the user's first ⌘Z
+     * empties the form they were just given:
+     *
+     *     const { data } = useQuery(...);
+     *     const { baseline } = useUndo();
+     *     useEffect(() => { if (data) baseline(); }, [data, baseline]);
+     *
+     * Worth calling on every arrival, not just the first: a window kept open
+     * across a refetch, or one whose entity changes underneath it, wants the
+     * same treatment, and the call is idempotent for a form nobody has touched.
+     */
+    baseline: () => void;
+    /** False when the user may not edit this record, so custom UI can hide
+     *  itself the way `UndoControls` does. */
+    enabled: boolean;
+}
+/**
+ * The enclosing form's undo stack, for custom UI or to `clear()` on save.
+ * Everything is inert outside an {@link UndoProvider}.
+ */
+declare function useUndo(): UndoControlsApi;
+interface UndoableOptions {
+    /** Names the step in a button title: `"qty"`, `"line items"`. */
+    label: string;
+    /**
+     * Consecutive changes sharing a key fold into one step — pass the field name
+     * so a run of typing is one Undo rather than one per keystroke. Omit for a
+     * change that is already whole, like a bulk import or a deleted row.
+     */
+    coalesceKey?: string | null;
+}
+/**
+ * Put one piece of the form's state under the window's undo stack.
+ *
+ * `value` is watched; when it changes, the form as it stood beforehand becomes
+ * a step. `apply` puts a value back — the same setter the form already uses.
+ *
+ *     const [items, setItems] = useState<Line[]>([]);
+ *     useUndoable(items, setItems, { label: 'line items' });
+ *
+ * Registering more than one slice is the point: a step snapshots all of them
+ * together, so undoing restores a coherent form rather than one slice out of
+ * step with the rest.
+ *
+ * `value` must be the state itself, not something derived from it on the way
+ * in. A change is detected by identity, so `useUndoable(rows.filter(r => r.on),
+ * ...)` hands over a new array on every render and reads as a change every
+ * time — and since recording a step re-renders the provider, that closes a
+ * loop at render speed. The provider trips a runaway guard and says so rather
+ * than letting the tab hang, but the fix is at the call site: register the
+ * state, and derive from it afterwards.
+ */
+declare function useUndoable<T>(value: T, apply: (next: T) => void, opts: UndoableOptions): void;
+/**
+ * `useState`, with the value in the window's undo stack.
+ *
+ * Written to be a rename rather than an extra line, because the forms this is
+ * for hold their state in dozens of separate `useState` calls — one of them has
+ * forty-three. Adopting a form is then a per-line edit:
+ *
+ *     const [supplier, setSupplier] = useState('');
+ *     const [supplier, setSupplier] = useUndoableState('', { label: 'supplier' });
+ *
+ * Which also makes the choice legible: state left as plain `useState` is state
+ * deliberately kept out of the history. Keep it that way for anything that is
+ * not the user's input — a search box, fetched data, validation output, an
+ * initialisation guard. Undoing those puts stale results back on screen, and a
+ * reverted guard can re-fire the effect it exists to suppress.
+ *
+ * Pass `coalesceKey` for anything typed into, so a run of keystrokes is one
+ * Undo; the field's own name is the obvious key.
+ */
+declare function useUndoableState<T>(initial: T | (() => T), opts: UndoableOptions): [T, React.Dispatch<React.SetStateAction<T>>];
+
+/**
+ * Undo/redo for one open form — the pure half.
+ *
+ * A form window owns a single stack covering everything in it: its fields, its
+ * line-items table, a bulk import. One ⌘Z steps back the last thing the user
+ * did, whatever part of the form it happened in.
+ *
+ * The stack holds snapshots, not diffs. A step stores the value of every
+ * registered slice **as it was before the change**, so undoing restores the
+ * whole form to a coherent moment rather than replaying one slice out of step
+ * with the others. Forms are small — a few dozen fields and some line items —
+ * so whole-form snapshots stay cheap and the logic stays honest.
+ *
+ * Scope is the unsaved edit. History lives with the open window and dies with
+ * it; nothing here reverses a saved record.
+ */
+/** Registered slice id → that slice's value at the time of the snapshot. */
+type UndoSnapshot = Record<string, unknown>;
+interface UndoStep {
+    /** The form as it stood before this change. Undo restores exactly this. */
+    values: UndoSnapshot;
+    /** What the step was, for a button title: `"qty"`, `"import of 5 lines"`. */
+    label: string;
+    /**
+     * Consecutive changes sharing a non-null key fold into one step — typing in
+     * a field is one Undo, not one per keystroke. Null never folds.
+     */
+    coalesceKey: string | null;
+}
+interface UndoState {
+    past: UndoStep[];
+    future: UndoStep[];
+}
+
+export { ALT, ALT_SHIFT_D, ALT_SHIFT_E, ALT_SHIFT_N, Accordion, type AccordionItem, type AccordionProps, type ActivityKind, 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_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 PerfLogRecord, type PerfReading, type PerfReport, 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, beginWindowGesture, classifyActivity, classify as classifyPerf, commitExposeHighlight, confirm, confirmDestructive, createWindowRegistry, exitExposeMode, findDuplicateKeys, formatDate, getActiveWindowRoute, getExposeHighlight, getWindowPosition, glassStyle, inputClasses, isDevEnv, isInteracting, isMac, isSeverityTone, markMenuOpen, 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 };