efficient-shell 0.0.0 → 4.126.2

package/dist/index.d.ts

@@ -0,0 +1,2495 @@
+import { S as SearchConfig, C as ColumnDef, a as SortState, P as PaginatedResponse } from './index-dQia6NpB.js';
+export { A as ALT, b as ALT_SHIFT_D, c as ALT_SHIFT_E, d as ALT_SHIFT_N, e as APP_UPDATE_POLL_MS, f as Accordion, g as AccordionItem, h as AccordionProps, i as Align, j as AngleScale, k as AppUpdateBanner, l as AppUpdateBannerProps, m as AttachButton, n as AttachButtonProps, o as AttachmentDropZone, p as AttachmentDropZoneProps, q as AttachmentList, r as AttachmentListProps, s as AuthScreen, t as AuthScreenProps, u as Avatar, v as AvatarGroup, w as AvatarGroupProps, x as AvatarProps, y as AvatarSize, z as AvatarStatus, B as BackgroundVariant, D as BandScale, E as Banner, F as BannerEmphasis, G as BannerProps, H as BannerTone, I as BarChart, J as BarChartProps, K as BoxPlotBox, L as BoxPlotChart, M as BoxPlotChartProps, N as BrandAssetEditor, O as BrandAssetEditorProps, Q as BrandAssetPreview, R as BrandMark, T as BrandMarkProps, U as BrandMarkSlot, V as BrandMarkSurface, W as BrandMarkTreatment, X as BreadcrumbItem, Y as Breadcrumbs, Z as BreadcrumbsProps, _ as BudgetBar, $ as BudgetBarProps, a0 as BudgetState, a1 as Button, a2 as ButtonProps, a3 as ButtonSize, a4 as ButtonVariant, a5 as CHART_INK, a6 as CMD_A, a7 as CMD_DOT, a8 as CMD_ENTER, a9 as CMD_K, aa as CMD_S, ab as Calendar, ac as CalendarMode, ad as CalendarProps, ae as Candle, af as CandlestickChart, ag as CandlestickChartProps, ah as Card, ai as CardPadding, aj as CardProps, ak as CartesianPlot, al as CartesianPlotProps, am as CellStyle, an as ChartBackgroundVariant, ao as ChartBrush, ap as ChartBrushProps, aq as ChartCurve, ar as ChartDefs, as as ChartDefsProps, at as ChartDot, au as ChartDotProps, av as ChartDotVariant, aw as ChartFillVariant, ax as ChartFrame, ay as ChartFrameProps, az as ChartHighlightProvider, aA as ChartLegendEntry, aB as ChartLegendSwatch, aC as ChartRange, aD as ChartReferenceLine, aE as ChartRevealDirection, aF as ChartSkeleton, aG as ChartSkeletonProps, aH as ChartStatusTone, aI as ChartStrokeVariant, aJ as ChartTooltip, aK as ChartTooltipProps, aL as ChartTooltipRow, aM as ChatTemplate, aN as Checkbox, aO as CheckboxProps, aP as CheckoutTemplate, aQ as ChordChart, aR as ChordChartProps, aS as ColoredBadge, aT as ColoredBadgeProps, aU as ColumnChart, aV as ColumnChartProps, aW as ColumnSeries, aX as ComposerAttachments, aY as ComposerAttachmentsProps, aZ as ConfirmProvider, a_ as ContainerFillChart, a$ as ContainerFillChartProps, b0 as ContainerFillItem, b1 as CountBadge, b2 as CountBadgeProps, b3 as CountBadgeTone, b4 as Curve, b5 as DAY_MS, b6 as DEFAULT_SHELL_STRINGS, b7 as DashboardTemplate, b8 as DataTable, b9 as DataTableColumn, ba as DataTableColumnGroup, bb as DataTableHeader, bc as DataTablePage, bd as DataTableProps, be as DatePicker, bf as DatePickerProps, bg as DateRangePicker, bh as DateRangePickerProps, bi as DateTimePicker, bj as DateTimePickerProps, bk as DescriptionColumns, bl as DescriptionItem, bm as DescriptionList, bn as DescriptionListProps, bo as Dialog, bp as DialogProps, bq as DialogSize, br as Divider, bs as DividerProps, bt as DividerSpacing, bu as DonutChart, bv as DonutChartProps, bw as DonutSegment, bx as Drawer, by as DrawerProps, bz as DrawerSide, bA as DrawerSize, bB as DropdownMenu, bC as DropdownMenuAlign, bD as DropdownMenuItem, bE as DropdownMenuProps, bF as DropdownMenuSide, bG as DropdownPositionOptions, bH as ENTER, bI as EditableGrid, bJ as EditableGridProps, bK as EmailTemplate, bL as EmptyState, bM as EmptyStateProps, bN as ErrorBoundary, bO as ErrorBoundaryProps, bP as ErrorPage, bQ as ErrorPageProps, bR as FileIntake, bS as FilePicker, bT as FilePickerProps, bU as FillVariant, bV as FormError, bW as FormErrorSummary, bX as FormErrorSummaryProps, bY as FormField, bZ as FormFieldProps, b_ as FormLayoutPage, b$ as FunnelChart, c0 as FunnelChartProps, c1 as FunnelStage, c2 as GLASS_DIVIDER, c3 as GLASS_INPUT_BG, c4 as GROUP_COLORS, c5 as GROUP_COLORS_SOLID, c6 as GalleryTemplate, c7 as Gap, c8 as GlobalSearch, c9 as GlobalSearchProps, ca as Grid, cb as GridCols, cc as GridColumn, cd as GridProps, ce as HeatmapChart, cf as HeatmapChartProps, cg as HelpCenter, ch as HelpCenterDoc, ci as HelpCenterProps, cj as HistogramBin, ck as HistogramChart, cl as HistogramChartProps, cm as INPUT_BASE, cn as INPUT_SIZES, co as IconButton, cp as IconButtonProps, cq as Inline, cr as InlineProps, cs as Input, ct as InputNumber, cu as InputNumberProps, cv as InputProps, cw as InputSize, cx as Justify, cy as Kanban, cz as KanbanColumn, cA as KanbanProps, cB as Kbd, cC as KbdProps, cD as KbdSize, cE as Label, cF as LabelProps, cG as LadderScale, cH as LineChart, cI as LineChartProps, cJ as LineChartSeries, cK as LinearScale, cL as ListFooter, cM as ListLoadError, cN as ListLoadErrorProps, cO as LoadingSpinner, cP as LoadingSpinnerProps, cQ as MAX_FRACTION_DIGITS, cR as MENU_MAX_HEIGHT, cS as MOD, cT as MOTION, cU as Markdown, cU as MarkdownLite, cV as MarkdownLiteProps, cV as MarkdownProps, cW as MediaUploadField, cX as MediaUploadFieldProps, cY as MediaUploadGrid, cZ as MediaUploadGridItem, c_ as MediaUploadGridProps, c$ as MenuPos, d0 as Meter, d1 as MeterProps, d2 as MetricBar, d3 as MetricBarProps, d4 as Milestone, d5 as MilestoneKind, d6 as MilestoneTimeline, d7 as MilestoneTimelineProps, d8 as NEXT_CHUNK_PATH_PREFIX, d9 as NativeSelect, da as NumericKeypad, db as NumericKeypadProps, dc as OVERLAY_OPEN_EVENT, dd as POPUP_MAX_WIDTH, de as POST_PRODUCTION_STATUSES, df as PageHeader, dg as PageHeaderProps, dh as Pagination, di as PaginationProps, dj as PaperclipGlyph, dk as Paragraph, dl as ParagraphProps, dm as PieChart, dn as PieChartProps, dp as PieSegment, dq as PlotGeometry, dr as Point, ds as PopupMenu, dt as PopupMenuDivider, du as PopupMenuItem, dv as PopupMenuItemProps, dw as PopupMenuLabel, dx as PopupMenuProps, dy as PopupSubmenu, dz as PopupSubmenuProps, dA as PortalBrandingContextValue, dB as PortalBrandingProvider, dC as PortalBrandingProviderProps, dD as ProductionTimeline, dE as ProductionTimelineProps, dF as ProductionTimelineSnapshot, dG as ProgressItem, dH as PublicPortal, dI as PublicPortalBranding, dJ as RADAR_SERIES_CAP, dK as RadarAxis, dL as RadarChart, dM as RadarChartProps, dN as RadarSeries, dO as RadialBarChart, dP as RadialBarChartProps, dQ as RadialBarRow, dR as Radio, dS as RadioGroup, dT as RadioGroupOption, dU as RadioGroupOrientation, dV as RadioGroupProps, dW as RadioProps, dX as Range, dY as RangeChart, dZ as RangeChartProps, d_ as RangeRow, d$ as RankedBars, e0 as RankedBarsProps, e1 as RankedBarsRow, e2 as ResolvedPortalBrandAsset, e3 as Result, e4 as ResultProps, e5 as ResultStatus, e6 as RevealDirection, e7 as SCATTER_SERIES_CAP, e8 as SERIES_SLOT_COUNT, e9 as SERIES_VARS, ea as SHIFT, eb as STAGES, ec as STALE_CHUNK_RELOAD_COOLDOWN_MS, ed as STALE_CHUNK_RELOAD_KEY, ee as STATUS_VARS, ef as SankeyChart, eg as SankeyChartProps, eh as SankeyLink, ei as SankeyNode, ej as ScatterChart, ek as ScatterChartProps, el as ScatterPoint, em as ScatterSeries, en as SearchProvider, eo as SearchResult, ep as SearchableOption, eq as SearchableSelect, er as SearchableSelectProps, es as Segmented, et as SegmentedOption, eu as SegmentedProps, ev as SegmentedSize, ew as Select, ex as SelectOption, ey as SelectProps, ez as SemanticGroup, eA as SettingRow, eB as SettingRowProps, eC as SeverityTone, eD as ShellPrefsAdapter, eE as ShellPrefsProvider, eF as ShellStrings, eG as ShellStringsOverride, eH as ShellStringsProvider, eI as SidebarActionButton, eJ as SidebarActionButtonProps, eK as SidebarGroupLabel, eL as SidebarLayout, eM as SidebarLayoutProps, eN as SidebarNavItem, eO as SidebarNavItemProps, eP as Skeleton, eQ as SkeletonProps, eR as SkeletonVariant, eS as Snippet, eT as SnippetProps, eU as SnippetSize, eV as SnippetVariant, eW as Sparkline, eX as SparklineProps, eY as Stack, eZ as StackProps, e_ as StaleChunkReloadOptions, e$ as StatCard, f0 as StatCardProps, f1 as StatTile, f2 as StatTileProps, f3 as Statistic, f4 as StatisticProps, f5 as StatisticSize, f6 as StatisticTone, f7 as StatusBadge, f8 as StatusBadgeProvider, f9 as StatusEmphasis, fa as StepItem, fb as Stepper, fc as StepperProps, fd as StrokeVariant, fe as SunburstChart, ff as SunburstChartProps, fg as SunburstNode, fh as Switch, fi as SwitchProps, fj as SwitchSize, fk as TabItem, fl as Tabs, fm as TabsProps, fn as TagInput, fo as TagInputOption, fp as TagInputProps, fq as Text, fr as TextProps, fs as TextSize, ft as TextTone, fu as TextWeight, fv as Textarea, fw as TextareaProps, fx as Theme, fy as TileButton, fz as TileButtonProps, fA as TileSize, fB as TimePicker, fC as TimePickerProps, fD as TimeSeriesChart, fE as TimeSeriesChartProps, fF as TimeSeriesSeries, fG as TimelineMarker, fH as TimelineMarkerKind, fI as TimelineReport, fJ as TimelineScrubProgress, fK as TimelineTrack, fL as TimelineTrackItem, fM as TimelineTrackKind, fN as TimelineTrackPending, fO as TimelineTrackPhase, fP as TimelineTrackPlayback, fQ as TimelineTrackProps, fR as TimelineTrackThumb, fS as Title, fT as TitleLevel, fU as TitleProps, fV as ToastOptions, fW as ToastPlacement, fX as Tooltip, fY as TooltipProps, fZ as TopNav, f_ as TopNavItem, f$ as TopNavProps, g0 as TreemapChart, g1 as TreemapChartProps, g2 as TreemapItem, g3 as TreemapTile, g4 as UseAppUpdateOptions, g5 as UseProductionTimelineOpts, g6 as VERSION, g7 as VITE_PRELOAD_ERROR_EVENT, g8 as WaterfallChart, g9 as WaterfallChartProps, ga as WaterfallStep, gb as ZLayer, gc as Z_LAYERS, gd as angleScale, ge as appendKey, gf as applyThemePrefs, gg as arcPath, gh as areaBetween, gi as areaFrom, gj as autoHighlightIndex, gk as backspace, gl as bandScale, gm as binValues, gn as budgetState, go as bumpPath, gp as calcOverall, gq as calcReportOverall, gr as confirm, gs as confirmDestructive, gt as curvePath, gu as dashFor, gv as dismissPopups, gw as fillFor, gx as fillId, gy as fmtSliderDate, gz as formatDate, gA as fromDateKey, gB as glassStyle, gC as glowId, gD as groundId, gE as groupColors, gF as highlightOpacity, gG as inputClasses, gH as installStaleChunkReload, gI as isMac, gJ as isSeverityTone, gK as isStaleChunkError, gL as ladderScale, gM as linearPath, gN as linearScale, gO as logScale, gP as maskId, gQ as mediaFileName, gR as monotonePath, gS as niceMax, gT as polygonPoints, gU as popupBounds, gV as prompt, gW as radiusScale, gX as resolveBrandMarkTreatment, gY as resolvePortalBrandAsset, gZ as resolveSeriesColor, g_ as resolveTheme, g$ as seriesColor, h0 as severityOf, h1 as splinePath, h2 as squarify, h3 as stagger, h4 as stepPath, h5 as tabButtonId, h6 as tabPanelId, h7 as toDateKey, h8 as toDayMs, h9 as toISODate, ha as toast, hb as useAppUpdate, hc as useClickOutside, hd as useConfirm, he as useDropdownPosition, hf as useFocusTrap, hg as useHighlight, hh as useIsMobile, hi as useLocalStoragePrefs, hj as usePlotWidth, hk as usePortalBranding, hl as useProductionTimeline, hm as useScrollLock, hn as useShellPrefs, ho as useShellStrings, hp as useTheme } from './index-dQia6NpB.js';
+export { FileIntakeAlert, FileIntakeLimits, FileIntakeOptions, FileRejection, FileRejectionReason, acceptsFile, useFileIntake } from './file-intake/index.js';
+import { W as WindowRegistry } from './types-BOinJXUf.js';
+export { M as ModalRegistryEntry, P as PageRegistryEntry, a as WindowRegistryEntry, i as isEntityEntry, b as isPageEntry, s as setShellWindowRegistry } from './types-BOinJXUf.js';
+import * as react from 'react';
+import react__default, { ReactNode, Component, ErrorInfo, Dispatch, SetStateAction, RefObject } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _tanstack_query_core from '@tanstack/query-core';
+import { AxiosInstance } from 'axios';
+
+/**
+ * createWindowRegistry — composes a window registry from one or more partial
+ * registry maps. Used at the consumer's App layer to merge package-bundled
+ * apps with the consumer's own entity windows.
+ *
+ *   const windows = createWindowRegistry(
+ *     bundledApps,        // utility + document + web apps from the package
+ *     entityWindows,      // consumer-defined entity windows (e.g. Sales Order, Invoice)
+ *   );
+ *
+ * Later partials override earlier ones on the same key — handy when a
+ * consumer wants to swap a built-in app for their own variant.
+ */
+
+declare function createWindowRegistry(...partials: WindowRegistry[]): WindowRegistry;
+
+/**
+ * Nav data types used by <Layout> + <StartMenu>. The actual sections, icons,
+ * and categories are consumer-supplied via Layout props — the package never
+ * ships nav DATA, only the shape it expects.
+ */
+
+interface NavItem {
+    to: string;
+    label: string;
+    /** Optional compact wording used only inside navigation menus. Keep `label`
+     *  as the full semantic name for windows, search and assistive technology. */
+    menuLabel?: string;
+    perms?: string[];
+    /** Permissions the user must hold EVERY one of, unlike `perms` which needs
+     *  only one. For an entry whose page is gated on a narrower permission than
+     *  the one that puts it in the menu: listing both in `perms` would widen the
+     *  audience (it's an OR), so the extra one goes here instead. */
+    allPerms?: string[];
+    dividerAfter?: boolean;
+    /** An action instead of a destination. When set, choosing the row calls this
+     *  and opens no window — `to` is then only the row's key (and its `navIcons`
+     *  lookup), so give it one no page uses. The menu closes as it would after
+     *  opening a page. For rows whose target is not a window: signing in to
+     *  another tenant, say, which Sign Out is the built-in precedent for. */
+    onSelect?: () => void;
+    /** Optional sub-items, to any depth — a child may have children of its own.
+     *  Hovering the parent in <StartMenu> opens a nested flyout; in <Sidebar>
+     *  the parent becomes an inline sub-accordion. */
+    children?: NavItem[];
+}
+interface NavSection {
+    label: string;
+    /** Optional compact wording used only inside navigation menus. */
+    menuLabel?: string;
+    items: NavItem[];
+    perms?: string[];
+    /** Same all-of rule as `NavItem.allPerms`, for a whole section. */
+    allPerms?: string[];
+    /** Optional landing route for clicks on the section title itself
+     *  (e.g. R&D's `/rd` dashboard). */
+    to?: string;
+    /** Draw a divider under this section's row, so a consumer can split one
+     *  flat group into visual bands (e.g. an operator console pinned above the
+     *  ERP sections). Same knob as `NavItem.dividerAfter`, and drawn INSIDE the
+     *  section's wrapper so it stays below the row in the `flex-col-reverse`
+     *  Start menu a side/top taskbar renders. */
+    dividerAfter?: boolean;
+}
+interface VirtualSection {
+    label: string;
+    /** Optional compact wording used only inside navigation menus. */
+    menuLabel?: string;
+    items: NavItem[];
+    icon?: ReactNode;
+}
+interface StartMenuCategories {
+    /** Section labels rendered in the "ERP" group (bold, with section icon). */
+    erp: string[];
+    /** Section labels rendered in the "system" group. */
+    system: string[];
+    /** Optional virtual flyouts (e.g. a "Utilities" tray). */
+    virtual?: VirtualSection[];
+    /** Optional section labels pinned to the bottom of the menu, next to the user
+     *  profile, separated from the ERP group by a divider. */
+    footer?: string[];
+    /** Optional flat top-level items pinned to the bottom of the menu, next to
+     *  the user profile, separated from the ERP group by a divider. Unlike
+     *  `footer` (section labels rendered as flyouts), these render as direct
+     *  clickable rows — use for standalone destinations like System Preferences
+     *  or a bug-report link. */
+    footerItems?: NavItem[];
+}
+
+/**
+ * INTERNAL stub — package-side compatibility for files that legacy-imported
+ * default nav data from `shell-config/nav`. The package never ships nav
+ * DATA; consumers always supply `navSections` / `navIcons` / `sectionIcons` /
+ * `categories` as Layout props.
+ *
+ * Empty defaults exported here so the copied files compile during the
+ * extraction transition. Each consumer-facing field is also re-exported as
+ * a TYPE alias for code that only needed the shape.
+ */
+
+declare function setShellNavIcons(icons: Record<string, ReactNode>): void;
+
+/** Register an Escape interceptor; returns an unregister function. */
+declare function registerModalEscapeInterceptor(fn: (e: KeyboardEvent) => boolean): () => void;
+
+/**
+ * What Cmd/Ctrl+Enter clicks when a window has no `<form>` to `requestSubmit()`.
+ *
+ * Two kinds of entry, in descending order of how much we trust them:
+ *
+ *  - **Explicit** — `type="submit"`, the bare `data-submit` attribute, and the
+ *    `.btn-submit` utility class. These are how a consumer *declares* "this is
+ *    the submit", so they are the ones to reach for in new markup.
+ *  - **Legacy colour heuristic** — `.bg-green-600` / `.bg-blue-600`. From before
+ *    the explicit opt-ins existed, when the submit button was identified by
+ *    being the blue (or green, for approve/post) one. Kept because consumers
+ *    still ship plenty of it; do not add more colours here.
+ *
+ * `.btn-submit` was missing from this list until 4.76.0, which made converting a
+ * button from a hardcoded `bg-blue-600` fill to the themable `.btn-submit`
+ * utility silently drop it out of the selector — Cmd+Enter stopped working while
+ * the button's own ⌘⏎ badge went on advertising it. The admin portal hit this
+ * across ~26 buttons and worked around it by also adding `data-submit`.
+ *
+ * NOTE: a comma-separated `querySelector` returns the first match in **document
+ * order**, not the first *selector* that matches — so the order of the entries
+ * below is documentation, not precedence. When a panel holds several candidates,
+ * the earliest one in the DOM wins.
+ */
+declare const MODAL_SUBMIT_SELECTOR = "button[type=\"submit\"], button[data-submit], button.btn-submit, button.bg-green-600, button.bg-blue-600";
+/** Hook for widget components to register a settings handler for the right-click menu. */
+declare function useWidgetSettings(handler: () => void): void;
+/** Hook to add custom items to the window title menu from inside a modal */
+declare function useWindowMenuItem(label: string, onClick: () => void, icon?: React.ReactNode): void;
+/** Component that updates the surrounding window's title bar. Render anywhere
+ *  inside a Modal-rendered page. Cross-bundle safe (uses DOM traversal rather
+ *  than React Context, which has separate instances in each bundle). */
+declare function WindowTitle({ title }: {
+    title: string;
+}): react_jsx_runtime.JSX.Element;
+/** @deprecated Use <WindowTitle> instead — the hook variant doesn't work
+ *  across bundle boundaries (apps barrel has its own ModalIdContext). */
+declare function useWindowTitle(_title: string): void;
+/**
+ * Portal component — renders children into the nearest Modal's footer actions area.
+ * position="left" for destructive actions (Delete), default is right for primary actions.
+ */
+declare function CopyButton({ text }: {
+    text: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * The id of the `<Modal>` this component is rendered inside, or `''` outside one.
+ *
+ * This is the PRIVATE per-mount id (`modal-xxxxxx`) that `activationOrder` and
+ * the window-scoped CustomEvents carry — not the caller-supplied `windowKey`.
+ * Same context `useWindowMenuItem` and `useWidgetSettings` already read, and it
+ * reaches portal window content the same way theirs does.
+ *
+ * Use it to answer "was this event meant for MY window?", which
+ * {@link useModalActive} cannot: that asks "is the frontmost modal mine", and
+ * every nested dialog a form opens pushes itself onto `activationOrder`, so a
+ * form with a child dialog open reads as inactive.
+ */
+declare function useEnclosingModalId(): string;
+/** Hook to check if the current modal is active (frontmost) */
+declare function useModalActive(): boolean;
+declare function ModalActions({ children, position, quiet }: {
+    children: React.ReactNode;
+    position?: 'left' | 'right';
+    /** @internal Content that joins a footer but is no reason to show one — the
+     *  shell's own Undo/Redo pair. It does not tell the Modal the footer has
+     *  content. */
+    quiet?: boolean;
+}): react.ReactPortal | null;
+/**
+ * Cancel button that checks for unsaved changes before calling onClick.
+ * Automatically detects dirty state from the nearest Modal context.
+ */
+declare function CancelButton({ onClick, children, className }: {
+    onClick: () => void;
+    children?: React.ReactNode;
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Seed an initial position for a window — applied only when no saved
+ * position already exists for the given key. Use this from the consumer
+ * to lay out the first-run desktop without overwriting whatever the user
+ * has subsequently dragged the windows to.
+ *
+ * The key matches the window's `windowKey` — for `openPage('/weather')`
+ * that's `'page:/weather'`.
+ */
+declare function setWindowDefaultPosition(key: string, pos: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): void;
+/** Read the saved box for a window key (viewport-relative px), or null. */
+declare function getWindowPosition(key: string): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;
+/**
+ * Force a window's saved position — unlike `setWindowDefaultPosition` this
+ * overwrites any existing entry. Use when the consumer wants to deliberately
+ * (re)place a window, e.g. the Widget Manager dropping a freshly-added widget
+ * into a tidy top-left slot regardless of where it last sat. For `autoHeight`
+ * windows the `h` here is only a first-paint placeholder — the window
+ * re-measures its content height on open.
+ */
+declare function setWindowPosition(key: string, pos: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): void;
+interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    title: React.ReactNode;
+    /** Window icon — shown before title, clicking it opens window menu */
+    icon?: React.ReactNode;
+    /** Text to copy when the copy icon in the header is clicked (e.g. entity number) */
+    copyText?: string;
+    size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+    dirty?: boolean | 'auto';
+    onNext?: () => void;
+    onPrev?: () => void;
+    footer?: React.ReactNode;
+    /** When true, body uses overflow-hidden — child content manages its own scrolling */
+    bodyScroll?: false;
+    /** Custom minimize handler — called instead of the default global minimize */
+    onMinimize?: (savedBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        maximized: boolean;
+    }) => void;
+    /** Restore to a previously saved position/size */
+    initialBox?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        maximized: boolean;
+    };
+    /** Footer actions (right side) — alternative to ModalActions portal */
+    actions?: React.ReactNode;
+    /** Footer actions (left side) — alternative to ModalActions portal */
+    actionsLeft?: React.ReactNode;
+    /** The window is in an editing state — a draft, a duplicate, or Edit mode
+     *  on a detail — which is when the footer shows Undo/Redo for the form's
+     *  stack of its own accord. `WindowManager` sets it; a window that edits in
+     *  place says `useUndoCanEdit(true)` instead. */
+    editing?: boolean;
+    /** Allow the window to be pinned on top of all others */
+    allowPinOnTop?: boolean;
+    /** Initial position hint */
+    initialPosition?: 'top-right' | 'top-left';
+    /** Widget mode: no title/footer, drag anywhere, right-click context menu */
+    widget?: boolean;
+    /** Compact title bar: smaller header with title + close only, no minimize/maximize */
+    compact?: boolean;
+    /** App-style window: full title bar but body uses no padding so the app's own
+     *  chrome (toolbars, menus) sits flush against the window frame. For
+     *  self-chromed apps like Preview, Files, Browser. Implies `bodyScroll: false`
+     *  — apps manage their own scrolling internally. */
+    appStyle?: boolean;
+    /** Flush body: keeps the STANDARD full title bar and footer, but drops the
+     *  body padding so the content sits flush to the window edges (e.g. a
+     *  `<SidebarLayout>`). Implies `bodyScroll: false`. */
+    flushBody?: boolean;
+    /** Auto-size height based on content. Window's height adapts to whatever the
+     *  body renders; floored by `autoMinHeight` and capped to the available
+     *  viewport so nothing overflows the screen. Naturally-flowing content (a
+     *  form, a table) shrinks the window to hug it; a fill-height root (`h-full` /
+     *  `flex-1` between a fixed header and footer) keeps the normal size-ladder
+     *  height and scrolls internally rather than collapsing. */
+    autoHeight?: boolean;
+    /** Minimum height (px) when `autoHeight` is on. Defaults to 240. */
+    autoMinHeight?: number;
+    /** Fit the width to the content when the window opens: a body that would
+     *  scroll sideways grows the window until it doesn't, up to the work area.
+     *  Grow-only, and only for the first few seconds — never after the user
+     *  moves, resizes or maximizes it. On by default; `false` keeps the
+     *  size-ladder / `dimensions` width exactly. Widgets, `appStyle` windows and
+     *  mobile never fit. */
+    autoWidth?: boolean;
+    /** Custom menu items for widget right-click context menu */
+    widgetMenu?: React.ReactNode;
+    /** Custom window dimensions [width, height] in pixels */
+    dimensions?: [number, number];
+    /** Stable key for persisting window position to sessionStorage */
+    windowKey?: string;
+    /** windowKey of whichever window was active when this one opened. On
+     *  mobile, swipe-to-back broadcasts this value so the parent window can
+     *  un-hide itself underneath the sliding panel. */
+    openedFromKey?: string;
+    /** Per-section window accent (SG#00372): an `R G B` triple (e.g.
+     *  '91 141 190'). When set, the panel publishes it as the
+     *  `--window-accent-rgb` CSS custom property, and — if the user has turned
+     *  the `window_accent_stripe` preference on — renders a thin accent stripe
+     *  between the title bar and the body, so overlapping windows from
+     *  different app sections are distinguishable at a glance. The header
+     *  itself stays theme-neutral — themes and the user's custom header
+     *  colour are untouched. Absent = exactly the previous rendering.
+     *
+     *  The CSS custom property is published whenever `accentRgb` is passed,
+     *  independent of the preference, so consumer CSS can key off the section
+     *  accent even with the stripe switched off. */
+    accentRgb?: string;
+    children: React.ReactNode;
+}
+/**
+ * Bring the window with this stable key to the front — now if it is mounted,
+ * or the moment it mounts if it is not.
+ *
+ * This is the shell's answer to "the user asked for this window", and it is
+ * deliberately the ONLY way a window rises without the user touching the
+ * window itself. Nothing about rendering reaches this function: a background
+ * window that refetches, re-renders, or receives a push cannot call it, so it
+ * cannot jump in front of whoever is typing. Somebody has to ASK.
+ *
+ * The deferred half is not an edge case, it is the common one. A window that
+ * is closed has no modal to raise, so the very first "open this" arrives
+ * before React has rendered anything — the request waits here and `mountModal`
+ * claims it below. That makes first-open and re-open one code path instead of
+ * two, which is the whole point: the second one is what used to be missing.
+ *
+ * An outstanding request is SPENT by the mount that honours it — see
+ * {@link _frontRequest} for why that is safe for a StrictMode remount. It also
+ * expires unhonoured when the user puts a different window in front (see
+ * `activateModal`), or when the ask is withdrawn.
+ */
+declare function requestWindowFront(windowKey: string): 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;
+declare function getExposeHighlight(): string | null;
+declare function setExposeHighlight(id: string | null): void;
+/**
+ * Commit the current keyboard highlight: focus the highlighted window
+ * and exit exposé with the standard "picked tile glides back" animation.
+ * No-op when no highlight is set.
+ */
+declare function commitExposeHighlight(): void;
+
+declare function Modal({ open, onClose, title, icon, copyText, size, dirty, onNext, onPrev, footer, bodyScroll, onMinimize, initialBox, actions, actionsLeft, editing, allowPinOnTop, initialPosition, widget, compact, appStyle, flushBody, autoHeight, autoMinHeight, autoWidth, widgetMenu, dimensions, windowKey, openedFromKey, accentRgb, children }: ModalProps): react.ReactPortal | null;
+
+/**
+ * A target as the window receives it: what was asked for, plus the stamp that
+ * makes THIS staging distinct from the last one.
+ *
+ * The stamp is not decoration. Without it, staging is only observable when the
+ * target's contents change — so asking for the window that is already showing
+ * exactly what you asked for would be a no-op, and "New form" on top of an open
+ * blank form would neither reset it nor (before this module) raise it. Callers
+ * never set `nav`; staging does.
+ */
+type StagedTarget<T> = T & {
+    readonly nav: number;
+};
+interface WindowTargetOptions {
+    /**
+     * Whether staging this target should also bring the window forward.
+     * Defaults to `true`, because staging a target is how the product says
+     * "the user asked to see this".
+     *
+     * Pass `false` for the rare staging that is not a request to be looked at —
+     * restoring a session's window state on load, say, where several windows are
+     * re-staged at once and none of them was just asked for.
+     */
+    raise?: boolean;
+}
+interface WindowTarget<T> {
+    /** The stable key the window's `Modal` must be given, so the shell can find
+     *  it to raise. Read it straight off the channel:
+     *  `<Modal windowKey={myTarget.windowKey}>`. */
+    readonly windowKey: string;
+    /** Point the window at something — or `null` to close it. A non-null target
+     *  also brings the window forward, whether it was closed, open and buried, or
+     *  already showing this very thing. */
+    set(target: T | null, options?: WindowTargetOptions): void;
+    /** What is staged right now (`null` if nothing) — for readers outside React. */
+    get(): StagedTarget<T> | null;
+    /** Watch for stagings. Returns its own unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Create the staging channel for one app-mounted window.
+ *
+ * `windowKey` identifies the window to the shell and must match the `windowKey`
+ * given to that window's `Modal`. Use a stable, namespaced string — it also
+ * becomes the key the window's position and stacking order are remembered
+ * under, so it outlives a page refresh.
+ */
+declare function createWindowTarget<T extends object>(windowKey: string): WindowTarget<T>;
+/**
+ * Read the staged target inside the window's host component, re-rendering
+ * whenever a new one is staged — including a fresh staging of an identical
+ * target, which `nav` makes a distinct value.
+ *
+ * Replaces the `useState` + `useEffect(subscribe)` pair every hand-written
+ * version of this channel used to carry, and closes that pair's own gap: it
+ * reads the currently-staged target during render rather than after mount, so a
+ * host mounted while something is already staged shows it on its first frame.
+ */
+declare function useWindowTarget<T extends object>(target: WindowTarget<T>): StagedTarget<T> | null;
+
+/** Inline crash state rendered in place of a window's content. Centers itself
+ *  in whatever space the body gives it; `onReload` resets the owning boundary
+ *  so the content remounts from scratch.
+ *
+ *  One crash a remount can never fix: a lazy chunk the server no longer has,
+ *  because a deploy replaced the build under this tab (see `staleChunk.ts`).
+ *  Remounting re-imports the same missing file. For that error the button is
+ *  "Reload page" and reloads the document, which is the only recovery. */
+declare function WindowCrashedFallback({ error, onReload }: {
+    error: Error;
+    onReload: () => void;
+}): react_jsx_runtime.JSX.Element;
+interface WindowErrorBoundaryProps {
+    children: ReactNode;
+    /** Replaces the default inline {@link WindowCrashedFallback}. `reset`
+     *  clears the caught error so the children remount. */
+    fallback?: (error: Error, reset: () => void) => ReactNode;
+}
+/**
+ * Error boundary around a window's content. Without it, a page/entity
+ * component that throws during render propagates to the root and unmounts the
+ * entire desktop. With it, only the crashed window's body is replaced — the
+ * window chrome (close/minimize), the taskbar and every other window keep
+ * running. Modal wraps its body in one; WindowManager wraps each whole window
+ * in another as a last resort for crashes outside the body (e.g. a registry
+ * `title()` throwing on malformed data).
+ */
+declare class WindowErrorBoundary extends Component<WindowErrorBoundaryProps, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: unknown): {
+        error: Error;
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    reset: () => void;
+    render(): string | number | boolean | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+declare function ShortcutHelp(): react_jsx_runtime.JSX.Element;
+
+interface ShellContextMenuProps {
+    /** Turn this instance off — every right-click falls through to the browser.
+     *  Under `Layout`, pass `contextMenu={false}` to `Layout` instead: it mounts
+     *  its own instance. */
+    disabled?: boolean;
+}
+declare function ShellContextMenu({ disabled }?: ShellContextMenuProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * What the shell's global context menu should offer for a given right-click.
+ *
+ * Kept free of React (and of the DOM beyond the element it is handed) so the
+ * two rules that matter can be tested directly: which targets keep the
+ * browser's own menu, and which items a click produces.
+ */
+/** Opt-out attribute: anything inside `[data-native-context-menu]` keeps the
+ *  browser's menu. For surfaces the shell has no business re-skinning — an
+ *  embedded viewer, a third-party widget. */
+declare const NATIVE_MENU_ATTR = "data-native-context-menu";
+/**
+ * Does this target keep the browser's native menu?
+ *
+ * Text inputs, textareas and contenteditable do, deliberately: the browser's
+ * spellcheck suggestions and "Add to dictionary" cannot be rebuilt by a web
+ * page, and a Paste item of our own would need a clipboard permission prompt.
+ * Images, canvases and media do for the same reason — Save / Copy image and
+ * the playback controls are the browser's. The shell menu is for everywhere
+ * else.
+ */
+declare function keepsNativeMenu(target: EventTarget | null): boolean;
+type ShellContextKind = 'selection' | 'link' | 'default';
+interface ShellContextTarget {
+    /** The most specific thing under the pointer — what the menu leads with. */
+    kind: ShellContextKind;
+    /** Trimmed selection text, when something is selected. */
+    selectionText?: string;
+    /** Absolute href of the nearest enclosing link. */
+    linkUrl?: string;
+}
+/**
+ * Describe a right-click: what was under the pointer, and what is selected.
+ *
+ * A selection inside a link reports both, so the menu can offer both sections
+ * the way a browser's does; `kind` names whichever the menu should lead with.
+ */
+declare function describeContextTarget(target: EventTarget | null, selectionText?: string | null, baseUrl?: string): ShellContextTarget;
+
+/**
+ * Copy, then say so: `"<label> copied"`, or an error toast when the browser
+ * refused. `label` names what was copied ("Text", "Link address", "3 rows",
+ * a column heading) and is shown as written — the failure message leaves it
+ * out, so a heading like "PO #" is never lower-cased into a sentence.
+ */
+declare function copyToClipboard(label: string, text: string, html?: string): Promise<boolean>;
+
+/** Generic notification shape consumed by the shell. Consumer-specific
+ * fields live on `extra` (or just on additional properties — TS structural
+ * typing is permissive). */
+interface ShellNotification {
+    id: string;
+    title: string;
+    message?: string;
+    entity_type?: string;
+    entity_id?: string;
+    entity_label?: string;
+    is_read: boolean;
+    actor_name?: string;
+    created_at: string;
+}
+/** Config bundle for the notification system. Supplied by the consumer;
+ * the shell never calls a hardcoded URL. */
+interface NotificationsConfig {
+    /** Hook called inside <NotificationBell> on every render. Return the
+     *  current unread count for the signed-in user. */
+    useUnreadCount: () => number;
+    /** Fetcher for the dropdown list (most recent first). */
+    list: (params?: {
+        page_size?: number;
+    }) => Promise<{
+        results: ShellNotification[];
+    }>;
+    /** Mark a single notification as read. */
+    markRead: (id: string) => Promise<unknown>;
+    /** Mark every unread notification as read. */
+    markAllRead: () => Promise<unknown>;
+    /** Click handler for a notification item. */
+    onItemClick: (notif: ShellNotification) => void;
+    /** Click handler for "View all notifications". When omitted, the link is hidden. */
+    onViewAll?: () => void;
+}
+interface NotificationBellProps extends NotificationsConfig {
+    popDirection?: 'left' | 'right';
+}
+declare function NotificationBell({ useUnreadCount, list, markRead, markAllRead, onItemClick, onViewAll, popDirection, }: NotificationBellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * System-tray badge shown only when the app is served from a developer's own
+ * machine (localhost / 127.0.0.1). Drop it into the host's `taskbarTrayLeft`
+ * slot — it renders nothing off-localhost, so it's safe to leave wired on every
+ * build. Visibility is gated on the runtime hostname; see utils/env.ts.
+ */
+declare function DevIndicator(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Dev-environment detection + browser chrome.
+ *
+ * A deployed bundle is byte-identical across hosts (CI builds once and promotes
+ * the same image between environments), so build-time signals like
+ * `import.meta.env.MODE` can't tell a developer's machine from a deployed site —
+ * only the runtime hostname can. `isDevEnv()` is therefore gated on
+ * `localhost`/`127.0.0.1`, and everything dev-only (the <DevIndicator/> tray
+ * badge, the `[DEV]` tab-title prefix) keys off it so it never leaks onto a
+ * deployed host.
+ */
+/** Tooltip/banner copy for the dev indicator. */
+declare const DEV_BANNER_TEXT = "LOCAL DEV ENVIRONMENT \u2014 running against your local backend; not connected to the live system";
+/**
+ * True only when served from a developer's own machine.
+ *
+ * Gated on `localhost`/`127.0.0.1` only (not `*.local` mDNS names), so a
+ * teammate reaching a dev server over the LAN doesn't get the dev chrome.
+ */
+declare function isDevEnv(): boolean;
+/**
+ * Apply local-dev browser chrome: prefix the tab title with `[DEV]` and,
+ * optionally, swap the favicon. No-op outside localhost. Idempotent — safe to
+ * call at startup and again whenever a route overwrites `document.title`.
+ *
+ * Call before React mounts (e.g. in `main.tsx`) so the title is correct on the
+ * first paint. Pass `faviconHref` only if the host actually ships that asset.
+ */
+declare function applyDevTitle(opts?: {
+    faviconHref?: string;
+}): void;
+
+interface SavedBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    maximized: boolean;
+}
+interface MinimizedItem {
+    id: string;
+    type: 'part_number' | 'modal' | 'page';
+    label: string;
+    /** Route path for icon lookup (e.g. '/orders', '/invoices') */
+    route?: string;
+    savedBox?: SavedBox;
+    /** Entity registry key (e.g. 'order', 'manufacturer') for restore */
+    entityType?: string;
+    /** Entity UUID for API fetch on cross-page restore */
+    entityId?: string;
+    /** Cached entity data for instant rendering while refetch happens */
+    entitySnapshot?: any;
+    /** windowKey of the window that was active when this opened — used by the
+     *  mobile swipe-to-back gesture to reveal the parent (e.g. the list a
+     *  detail entity was opened from) instead of the home wallpaper. Undefined
+     *  when this window opened directly from home / the start menu. */
+    openedFrom?: string;
+}
+interface MinimizedContextType {
+    openWindows: MinimizedItem[];
+    openEntity: (entityType: string, entityId: string, snapshot?: any, label?: string, route?: string) => void;
+    openPage: (path: string) => void;
+    closeEntity: (id: string) => void;
+    /** @deprecated kept for backward compat — aliases openEntity/closeEntity */
+    minimize: (item: MinimizedItem) => void;
+    items: MinimizedItem[];
+    restore: (item: MinimizedItem) => void;
+    remove: (id: string) => void;
+    restoreIfMinimized: (label: string) => boolean;
+    openItems: MinimizedItem[];
+}
+/**
+ * Registers controlled dirty state with the enclosing shell window, so closing
+ * it asks before discarding. Works in both kinds of window the shell owns the
+ * Modal for: page windows and entity/detail windows.
+ *
+ * While dirty it also holds the page itself: a reload, Back out of the app or
+ * closing the tab gets the browser's "Leave site?" prompt first.
+ *
+ * Ignored — deliberately, and silently — in the one place the shell has no
+ * Modal to guard: a registry entry with `rendersOwnModal`, where the consumer
+ * renders its own Modal and should pass that Modal `dirty` directly. Also a
+ * no-op outside a WindowManager entirely.
+ */
+declare function useWindowDirty(dirty: boolean): void;
+declare function useWindowManager(): MinimizedContextType;
+/** Star button to favorite a document — saves to preferences.favorite_documents */
+declare function DocFavStar({ entityType, entityId, label }: {
+    entityType: string;
+    entityId: string;
+    label: string;
+}): react_jsx_runtime.JSX.Element;
+/** Public, framework-free helper: route ('/orders', '/qc-reports', …)
+ *  of the window the user is currently focused on. Returns undefined
+ *  when no app window is active (start menu / dashboard with nothing
+ *  open). Useful for code paths that fire outside React render — the
+ *  shell consumer can stamp metadata on a payload (e.g. "which module
+ *  is this bug report against?") without needing to lift state. */
+declare function getActiveWindowRoute(): string | undefined;
+declare function WindowManagerProvider({ children, windowAccentForRoute }: {
+    children: ReactNode;
+    /** SG#00372: optional per-section window accent. Called with each open
+     *  window's route ('/sales-orders', '/payments', …); return an `R G B`
+     *  triple (e.g. '91 141 190') to give that window a thin accent stripe
+     *  between its title bar and body (see Modal's `accentRgb`), or undefined
+     *  for no accent. The stripe is drawn only for users who have switched it
+     *  on in Customization → Windows; the mapping is still worth wiring
+     *  regardless, since it also publishes `--window-accent-rgb` per window.
+     *  The consumer owns the route→section→colour mapping; omitting the prop
+     *  keeps every window exactly as before. */
+    windowAccentForRoute?: (route: string) => string | undefined;
+}): react_jsx_runtime.JSX.Element;
+
+interface EntityWindowStateProps<T> extends EntityWindowFallbackProps {
+    entity: T | null | undefined;
+    children: (entity: T) => ReactNode;
+}
+interface EntityWindowFallbackProps {
+    isPending: boolean;
+    isFetching: boolean;
+    /**
+     * Whether the query is switched on. FALSE for a window whose detail fetch is
+     * deliberately skipped — a `new-` draft, a duplicate, or a host that never
+     * called `setShellApiClient`.
+     *
+     * This has to be passed, because a DISABLED TanStack query is
+     * `status: 'pending'` / `fetchStatus: 'idle'` forever, so `isPending` alone
+     * reads as "still loading" for a request that will never be made — and the
+     * window sits on a spinner it can never leave. `isLoading` (`isPending &&
+     * isFetching`) is the pair that already accounts for this, which is why the
+     * old inline check did not have the bug.
+     */
+    enabled?: boolean;
+    error: unknown;
+    onRetry: () => void;
+}
+declare function EntityWindowLoading(): react_jsx_runtime.JSX.Element;
+/**
+ * The no-data half of an entity window: what to show when there is no entity
+ * to render yet, or never will be. Split out from `EntityWindowState` because
+ * a `rendersOwnModal` entry supplies its own Modal only once it HAS an entity,
+ * so these states need a modal of their own to live inside.
+ */
+declare function EntityWindowFallback({ isPending, isFetching, enabled, error, onRetry, }: EntityWindowFallbackProps): react_jsx_runtime.JSX.Element;
+/**
+ * Owns the no-data states for an entity window. Existing data always wins so
+ * background refreshes never replace a usable detail with transient chrome.
+ */
+declare function EntityWindowState<T>({ entity, children, ...fallback }: EntityWindowStateProps<T>): 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 What's New modal references the consumer-side
+ * changelog. The package ships no built-in changelog; the consumer wires
+ * their own through `DesktopHostConfig.productChangelog` (the What's New
+ * dialog reads it first, and this empty default keeps the import compiling
+ * when they don't). Layout's `branding` prop carries the rest of the visual
+ * identity — name, logo, tagline.
+ */
+interface ChangelogEntry {
+    version: string;
+    date: string;
+    changes: string[];
+}
+
+type PreviewFileKind = 'pdf' | 'dxf' | '3d' | 'image' | 'csv';
+
+interface DesktopItem {
+    entityType: string;
+    entityId: string;
+    label: string;
+    x?: number;
+    y?: number;
+    folderId?: string;
+    folderX?: number;
+    folderY?: number;
+    filePath?: string;
+    fileKind?: PreviewFileKind;
+}
+
+interface DesktopFolder {
+    id: string;
+    name: string;
+    x?: number;
+    y?: number;
+}
+interface StickyEntityRef {
+    /** Window-registry key used by `openEntity`. */
+    entityType: string;
+    entityId: string;
+    /** Optional human-readable label (defaults to `${prefix}#${number}`). */
+    label?: string;
+    /** Optional pre-fetched entity payload passed to openEntity as snapshot. */
+    snapshot?: unknown;
+}
+type StickyResolver = (prefix: string, number: string) => Promise<StickyEntityRef | null>;
+/** Optional items in the desktop right-click menu that a consumer can hide via
+ *  {@link DesktopHostConfig.hiddenContextMenuItems} — e.g. when they're surfaced
+ *  under Preferences instead. `'customization'` is the Preferences/Customization
+ *  shortcut, `'favorites'` the Favorites shortcut, `'about'` the About item,
+ *  `'perf-stats'` the performance-overlay toggle. */
+type DesktopContextMenuItem = 'customization' | 'favorites' | 'about' | 'perf-stats';
+interface DesktopHostConfig {
+    /** Product name shown in the About dialog and desktop context menu. */
+    productName?: string;
+    /** Tagline shown under the product name in the About dialog. */
+    productTagline?: string;
+    /** Icon URL shown in the About dialog. Defaults to `/favicon.svg`. */
+    productIcon?: string;
+    /** Version string shown on the desktop watermark and About dialog. Falls
+     *  back to the react-os-shell package version if omitted. */
+    productVersion?: string;
+    /** Changelog rendered in the "What's New" dialog. Hidden when omitted. */
+    productChangelog?: ChangelogEntry[];
+    /** Copyright line in the About dialog footer. Hidden when omitted. */
+    productCopyright?: string;
+    /** Website URL in the About dialog footer. Hidden when omitted. */
+    productWebsite?: string;
+    /** Wallpaper picker options for the Customization settings page. */
+    wallpapers?: {
+        src: string;
+        label: string;
+    }[];
+    /** Resolves sticky-note refs (e.g. "SO#27150") to window-registry coords. */
+    stickyResolver?: StickyResolver;
+    /** Persists the user's desktop shortcut list. */
+    saveShortcuts?: (items: DesktopItem[]) => void | Promise<void>;
+    /** Persists the user's folder list. */
+    saveFolders?: (folders: DesktopFolder[]) => void | Promise<void>;
+    /** Persists the snap-to-grid preference. */
+    saveSnap?: (snap: boolean) => void | Promise<void>;
+    /** Persists the user's notepad / sticky-note content. */
+    saveNotes?: (notes: unknown[]) => void | Promise<void>;
+    /** Desktop right-click menu items to hide (all shown by default). Pass keys
+     *  here when the consumer surfaces them elsewhere — e.g. under Preferences. */
+    hiddenContextMenuItems?: DesktopContextMenuItem[];
+    /** Open the consumer's own "report a bug / suggestion" UI. When set, the
+     *  desktop and taskbar right-click menus show a "Suggestion or Bug" item that
+     *  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;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useDesktopHost(): DesktopHostConfig;
+declare function Desktop({ profile }: {
+    profile: any;
+}): react_jsx_runtime.JSX.Element;
+
+interface MobileAppConfig {
+    /** Link the primary button opens — a native deep link, an App Store /
+     *  Play Store page, or a mobile-optimised web app. When omitted the screen
+     *  still renders (branding + message) but without a call-to-action. */
+    url?: string;
+    /** Primary button label. Defaults to `Open the app`. */
+    ctaLabel?: string;
+    /** Headline. Defaults to a message built from the product name. */
+    heading?: string;
+    /** Supporting copy under the headline. */
+    description?: string;
+}
+
+/**
+ * The product's visual identity, in one object: the start-menu button, the
+ * startup splash, the logout cover and the mobile landing all read from it.
+ * The About dialog and What's New changelog belong to `DesktopHostConfig`
+ * (`productName`, `productIcon`, `productChangelog`, …), which configures the
+ * desktop; this configures the chrome around it.
+ */
+interface ShellBranding {
+    /** Product name — start-menu button, startup splash, mobile landing. */
+    productName?: string;
+    /** Logo URL — start-menu button, splash and logout covers. Defaults to `/favicon.svg`. */
+    logo?: string;
+    /** Apply the shared contrast treatment to arbitrary tenant artwork. */
+    adaptiveLogo?: boolean;
+    /** Server-detected transparency hint for `logo`. */
+    logoHasAlpha?: boolean | null;
+    /** Server-detected tone hint for `logo`. */
+    logoIsLight?: boolean | null;
+    /** Line under the product name on the splash and logout covers —
+     *  typically the company name. */
+    tagline?: string;
+}
+interface LayoutProps {
+    /** One-object form of the brand fields below; its fields win over them, so
+     *  a consumer can move over field by field. */
+    branding?: ShellBranding;
+    /** Brand label rendered on the start-menu button. */
+    productName?: string;
+    /** Icon URL rendered next to the brand label. Defaults to `/favicon.svg`. */
+    productIcon?: string;
+    /** Wallpaper image URLs for the desktop background. When omitted, falls back
+     *  to the wallpapers registered on the `DesktopHostProvider` (the same pool the
+     *  Customization picker shows); with neither, the desktop renders no image. */
+    wallpapers?: string[];
+    /** Override the default nav sections shown in the start menu. */
+    navSections?: (NavSection | NavItem)[];
+    /** Override the per-route icon map used by start menu and favorites. */
+    navIcons?: Record<string, ReactNode>;
+    /** Override the per-section header icon map used by start menu. */
+    sectionIcons?: Record<string, ReactNode>;
+    /** Override the start menu's section grouping + virtual flyouts. */
+    categories?: StartMenuCategories;
+    /** Notification system config — when omitted, the bell isn't rendered. */
+    notifications?: NotificationsConfig;
+    /** Universal search config — when omitted, Cmd-K opens the picker but no
+     *  results ever come back. */
+    search?: SearchConfig;
+    /** Custom node rendered in the system tray to the LEFT of the
+     *  notification bell (or above it on a vertical taskbar). Lets a host
+     *  app drop in icons like a server-status indicator without forking
+     *  the shell. The shell renders the node as-is — keep it small (a
+     *  single icon-sized button) so it fits the existing tray rhythm. */
+    taskbarTrayLeft?: ReactNode;
+    /** Taskbar clock popover config — lets the host surface per-day content
+     *  (e.g. tasks due that day) inside the mini month calendar. When omitted
+     *  the popover stays a plain date grid. */
+    clockCalendar?: ClockCalendarConfig;
+    /** Mobile-app link shown on phone/tablet-portrait viewports in place of the
+     *  desktop chrome. The shell has no built-in touch UI — wire a link to your
+     *  dedicated mobile app here (see MobileAppConfig). When omitted, small
+     *  screens get a plain "best viewed on desktop" notice. */
+    mobileApp?: MobileAppConfig;
+    /** The shell-wide right-click menu (`ShellContextMenu`). On by default;
+     *  `false` hands every right-click back to the browser — for a consumer
+     *  that is mid-migration, or that draws a menu of its own everywhere. */
+    contextMenu?: boolean;
+}
+interface ClockCalendarConfig {
+    /** Local dates (YYYY-MM-DD) to mark with a dot in the mini month grid —
+     *  typically days that have items on them. */
+    markedDates?: string[];
+    /** Render content for the selected day below the grid. The popover
+     *  defaults the selection to today when it opens, so clicking the clock
+     *  immediately shows today's items; clicking any day in the grid
+     *  re-renders the panel for that day (days outside the shown month also
+     *  flip the grid to their month). `close` dismisses the popover — call
+     *  it when a row click opens a window so the popup doesn't linger over
+     *  it. */
+    renderDay?: (dateISO: string, api: {
+        close: () => void;
+    }) => ReactNode;
+}
+declare function Layout({ branding, productName, productIcon, wallpapers, navSections, navIcons, sectionIcons, categories, notifications, search, taskbarTrayLeft, clockCalendar, mobileApp, contextMenu, }?: LayoutProps): react_jsx_runtime.JSX.Element;
+
+interface StartMenuProps {
+    open: boolean;
+    onClose: () => void;
+    openPage: (path: string) => void;
+    openWindows: {
+        route?: string;
+        label: string;
+    }[];
+    profile: any;
+    user: any;
+    onLogout: () => void;
+    onNavigate: (path: string) => void;
+    taskbarPosition: 'top' | 'bottom' | 'left' | 'right';
+    taskbarH: number;
+    taskbarW?: number;
+    /** Gap (px) between the menu and the taskbar edge; set per taskbar size by Layout. */
+    taskbarGap?: number;
+    size?: 'small' | 'medium' | 'large';
+    /** Override the default nav sections (sections + top-level items). */
+    navSections?: (NavSection | NavItem)[];
+    /** Per-route icon map for items in the menu. */
+    navIcons?: Record<string, ReactNode>;
+    /** Per-section header icon map. */
+    sectionIcons?: Record<string, ReactNode>;
+    /** Section grouping + virtual flyouts (Utilities-style trays). */
+    categories?: StartMenuCategories;
+}
+declare function StartMenu({ open, onClose, openPage, profile, user, onLogout, taskbarPosition, taskbarH, taskbarW, taskbarGap, size, navSections, navIcons, sectionIcons, categories, }: StartMenuProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Widget gallery — the "manage widgets on the desktop" surface.
+ *
+ * Enumerates every widget-flagged page in the live window registry (so it
+ * automatically lists whatever the consumer registered, not just the bundled
+ * five) and cross-references the window manager's `openWindows` to know which
+ * are currently sitting on the desktop. Adding a widget calls `openPage`
+ * (which drops the chrome-less panel onto the desktop and persists it via the
+ * normal open-windows session store); removing one calls `closeEntity` on the
+ * live window. No new persistence layer — it drives the same plumbing the
+ * Start Menu already uses.
+ *
+ * Surfaced from the desktop right-click menu ("Manage Widgets…") and exported
+ * so a consumer can also register it as a window or wire it to a tray button.
+ */
+declare function WidgetManager({ open, onClose }: {
+    open: boolean;
+    onClose: () => void;
+}): react_jsx_runtime.JSX.Element | null;
+
+/** Sections that can be omitted from the inline Customization page when the
+ *  consumer renders them elsewhere (e.g. as separate entries in SystemPreferences). */
+type CustomizationOmitSection = 'behavior' | 'desktop';
+/** A logical group of the Customization page. Pass `section` to render only one
+ *  group, so the page can be split across separate SystemPreferences entries
+ *  (Appearance / Layout / Behavior). Omit `section` to render the whole page. */
+type CustomizationSection = 'appearance' | 'layout' | 'behavior';
+interface CustomizationProps {
+    omit?: readonly CustomizationOmitSection[];
+    /** Render only one logical group of settings. Omit to render everything. */
+    section?: CustomizationSection;
+}
+declare function Customization({ omit, section }?: CustomizationProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Standalone Behavior settings panel — window position, double-click,
+ * default window size, plus the two desktop-related toggles
+ * (Show version on desktop, Enter full screen mode automatically).
+ *
+ * Reads/writes shell prefs via `useShellPrefs()`. Suitable for use as a
+ * section in `SystemPreferences` or rendered standalone.
+ */
+declare function BehaviorPanel(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Standalone Sounds settings panel — sound effects toggle + per-event
+ * sound-pack picker. Reads/writes the shell's `erp_sounds` and
+ * `erp_sound_config` localStorage keys. Plays a preview when a pack is
+ * picked. Suitable as a section in `SystemPreferences` or rendered
+ * standalone.
+ */
+declare function SoundsPanel(): react_jsx_runtime.JSX.Element;
+
+/** One section in the SystemPreferences sidebar. */
+interface SystemPreferencesSection {
+    /** Unique key, e.g. `'notifications'`, `'customization'`. */
+    key: string;
+    /** Sidebar label, e.g. "Notifications". */
+    label: string;
+    /** Short description shown under the label in the sidebar. */
+    description?: string;
+    /** Sidebar icon (any ReactNode — typically a 4×4 svg). */
+    icon?: ReactNode;
+    /** Body renderer. Receives no args; access shell prefs via your own hook. */
+    render: () => ReactNode;
+}
+interface SystemPreferencesProps {
+    /** Ordered sections — left sidebar lists these top-to-bottom, the matching
+     *  body renders on the right. The first section is selected by default
+     *  unless `defaultSelected` is supplied. */
+    sections: readonly SystemPreferencesSection[];
+    /** Key of the section to highlight on first render. Falls back to the first
+     *  section in `sections`. */
+    defaultSelected?: string;
+    /** Optional className applied to the outer flex container. */
+    className?: string;
+}
+/**
+ * Two-pane settings window: a fixed sidebar of sections on the left, the
+ * active section's body on the right. Consumers compose by passing
+ * `sections` — each entry has a `key`, `label`, optional `icon` and
+ * `description`, and a `render()` callback that returns the body JSX.
+ *
+ * The shell exposes ready-made panels (`Customization`, `BehaviorPanel`,
+ * `SoundsPanel`) that can be used as section bodies directly; portals
+ * add their own sections (notification subscriptions, delivery defaults,
+ * personal formatting prefs, etc.) alongside.
+ *
+ * Example:
+ * ```tsx
+ * <SystemPreferences sections={[
+ *   { key: 'notifications', label: 'Notifications', icon: <BellIcon />, render: () => <MyNotifications /> },
+ *   { key: 'customization', label: 'Customization', icon: <PaintBrushIcon />, render: () => <Customization omit={['behavior','desktop']} /> },
+ *   { key: 'behavior',      label: 'Behavior',      icon: <Cog6ToothIcon />,   render: () => <BehaviorPanel /> },
+ *   { key: 'sounds',        label: 'Sounds',        icon: <SpeakerWaveIcon />, render: () => <SoundsPanel /> },
+ * ]} />
+ * ```
+ */
+declare function SystemPreferences({ sections, defaultSelected, className, }: SystemPreferencesProps): react_jsx_runtime.JSX.Element;
+
+interface ImageAnnotatorHandle {
+    copy: () => Promise<void>;
+    save: () => Promise<void>;
+}
+interface ImageAnnotatorProps {
+    src: string;
+    filename: string;
+    /** Standalone-mode: when provided, an Apply pill is rendered in the
+     *  annotator's toolbar that composites the current canvas + SVG into a PNG
+     *  blob and hands it back. Used by callers like the bug-report dialog that
+     *  embed the annotator outside the Preview app and want the result. */
+    onApply?: (blob: Blob) => void;
+    /** Standalone-mode companion to `onApply` — Cancel pill that lets the
+     *  consumer dismiss the annotator without applying. */
+    onCancel?: () => void;
+}
+declare const ImageAnnotator: react.ForwardRefExoticComponent<ImageAnnotatorProps & react.RefAttributes<ImageAnnotatorHandle>>;
+
+interface EntityListColumn {
+    key: string;
+    label: string;
+    defaultWidth?: number;
+    minWidth?: number;
+    defaultHidden?: boolean;
+    sortField?: string;
+    headerNode?: ReactNode;
+}
+/** A page-supplied entry in the right-click bulk menu (e.g. invoice Post /
+ *  Cancel). `onClick` receives the currently-selected rows. Set `divider` to
+ *  render a separator above the item, `danger` for a destructive tint. */
+interface EntityListContextAction<T = unknown> {
+    label: string;
+    onClick: (items: T[]) => void;
+    danger?: boolean;
+    disabled?: boolean;
+    divider?: boolean;
+}
+interface EntityListProps<T> {
+    items: T[];
+    isLoading: boolean;
+    emptyState: ReactNode;
+    totalCount?: number;
+    /** When true and no rows have loaded yet, render {@link ListLoadError}
+     *  (with a retry) instead of `emptyState` — so a failed fetch reads as an
+     *  error, not "nothing here". Wire `useInfiniteScroll`'s `isError`. A
+     *  mid-scroll next-page failure (rows already loaded) keeps the list.
+     *  Defaults to unset → behaviour unchanged for existing callers. */
+    isError?: boolean;
+    /** Retry handler for the error state — wire the data source's `refetch`.
+     *  It also backs the row menu's Refresh item. */
+    onRetry?: () => void;
+    /** Heading for the error state, e.g. "Couldn't load candidates". Omit for
+     *  {@link ListLoadError}'s generic "Couldn't load this list" — name the
+     *  entity where the list has one, so an outage reads as *this* list failing. */
+    errorTitle?: string;
+    /** Explanatory line under {@link EntityListProps.errorTitle}. Omit for
+     *  ListLoadError's generic connection/retry message. */
+    errorMessage?: string;
+    tableId: string;
+    columns: EntityListColumn[];
+    renderCell: (item: T, colKey: string) => ReactNode;
+    getRowId?: (item: T) => string | number;
+    sort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    onSort?: (field: string) => void;
+    selected: Set<string | number>;
+    setSelected: Dispatch<SetStateAction<Set<string | number>>>;
+    onRowClick: (item: T) => void;
+    onRowHover?: (item: T) => void;
+    getRowClassName?: (item: T) => string;
+    footerLabel: string;
+    footerExtra?: ReactNode;
+    sentinelRef?: RefObject<any>;
+    isFetchingNextPage?: boolean;
+    /** Perm codenames that gate "Save as default for all users" in the column
+     *  picker. Defaults to `['change_numberingconfig']` (admin-portal's proxy
+     *  for admin access). Pass `[]` to hide the link entirely. */
+    saveDefaultPerms?: string[];
+    /** Right-click row menu. Every list has one, with nothing to wire: Open (the
+     *  row right-clicked), Copy for text selected under the pointer, Copy
+     *  `<first column>` and Copy rows (the ticked rows as a table of the visible
+     *  columns in their on-screen order, which pastes into a spreadsheet as
+     *  cells), Select all, Clear selection, and Refresh when `onRetry` is wired.
+     *  Provide `exportEndpoint` (a list's `<base>/export_csv/` path, relative to
+     *  the api base) to add "Export selected to CSV", which downloads just the
+     *  ticked rows (`?ids=`, honouring the visible/ordered columns). Provide
+     *  `contextActions` for domain actions (e.g. invoice Post / Cancel); they sit
+     *  between the copy items and the selection items. */
+    exportEndpoint?: string;
+    exportFilename?: string;
+    contextActions?: (items: T[]) => EntityListContextAction<T>[];
+}
+/**
+ * The canonical pageless data grid for both portals. Wraps `<ResizableTable>`
+ * with selection-checkbox logic, keyboard navigation, the standardized list
+ * footer, an infinite-scroll sentinel hook-up, and a right-click row menu.
+ *
+ * Usage:
+ *
+ *   const { sort, onSort } = useSort('mid', 'asc', 'suppliers');
+ *   const { items, totalCount, isLoading, isFetchingNextPage, sentinelRef } =
+ *     useInfiniteScroll<Supplier>({ queryKey: ['suppliers', filters],
+ *                                   fetchFn: (p) => getSuppliers(p) });
+ *
+ *   <EntityList
+ *     items={items}
+ *     totalCount={totalCount}
+ *     isLoading={isLoading}
+ *     sentinelRef={sentinelRef}
+ *     isFetchingNextPage={isFetchingNextPage}
+ *     tableId="suppliers"
+ *     columns={SUPPLIER_COLUMNS}
+ *     renderCell={(s, k) => …}
+ *     sort={sort} onSort={onSort}
+ *     selected={selected} setSelected={setSelected}
+ *     onRowClick={(s) => openEntity('supplier', s.id, s, s.mid, '/suppliers')}
+ *     exportEndpoint="/suppliers/export_csv/" exportFilename="Suppliers.csv"
+ *     footerLabel="suppliers"
+ *     emptyState={<EmptyState message="No suppliers yet." />}
+ *   />
+ */
+declare function EntityList<T>(props: EntityListProps<T>): react_jsx_runtime.JSX.Element;
+
+interface ResizableTableProps {
+    tableId: string;
+    columns: ColumnDef[];
+    sort?: SortState;
+    onSort?: (field: string) => void;
+    footer?: React.ReactNode;
+    afterBody?: React.ReactNode;
+    /** Permission codename(s) that gate the "Save as default for all users" link
+     *  in the column picker. The shell's `useShellAuth().hasAnyPerm` is queried
+     *  against this list. Defaults to a single placeholder permission; consumers
+     *  with no admin gate can pass `[]` to hide the link entirely. */
+    saveDefaultPerms?: string[];
+    children: (orderedColumns: (ColumnDef & {
+        width: number;
+    })[]) => React.ReactNode;
+}
+/**
+ * Sticky-header, scrollable-body table primitive with:
+ * - drag-to-reorder columns (with a blue drop-indicator line)
+ * - resize columns by the right-edge handle
+ * - hide/show columns via a glass popover picker
+ * - admin-only "Save as default for all users" link in the picker
+ * - per-user persistence (via the shell-registered apiClient)
+ * - mobile-aware selection mode toggle
+ */
+declare function ResizableTable({ tableId, columns, sort, onSort, footer, afterBody, saveDefaultPerms, children, }: ResizableTableProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Keyboard + shift-click navigation for table rows.
+ *
+ * - J/K or Arrow keys to move focus
+ * - Enter to open the focused row (calls `onSelect`)
+ * - Space to toggle the focused row's checkbox (calls `onToggle`)
+ * - Shift+J/K to extend selection while moving
+ * - Shift+click to range-select (calls `onSelectRange`, which must ADD the range
+ *   rather than toggle it — the clicked checkbox is ticked on that assumption)
+ * - Cmd/Ctrl+A to select/deselect all (calls `onSelectAll`)
+ *
+ * Each list instance gates its document-level listeners on `useModalActive`
+ * so two open lists don't both react to the same shift-click.
+ */
+declare function useTableNav<T>(items: T[], onSelect: (item: T) => void, onToggle?: (item: T) => void, onSelectAll?: () => void, onSelectRange?: (from: number, to: number) => void): number;
+
+/**
+ * Resizable + reorderable + hideable column state for `<ResizableTable>`.
+ *
+ * Reads and persists per-user through the `<ShellPrefsProvider>` adapter
+ * (`prefs.columns_{tableId}`), with a 1-second debounce on the save, and reads
+ * per-viewport admin defaults through the shared
+ * `GET /auth/default-columns/{tableId}?viewport=…` probe.
+ *
+ * The prefs half used to be a raw `GET /auth/me/` fired from a `[tableId]`
+ * effect, outside react-query — so every list mount re-fetched the whole user
+ * profile (~1.5 MB on prod), on a client with no cache adapter and no in-flight
+ * dedupe, and a screen that also renders a column-aware CSV export paid for it
+ * twice. The adapter already holds that profile in one cached query, which is
+ * the same object the raw GET was reading `preferences` off (SG#00590).
+ *
+ * Three consequences worth knowing, because this is NOT behaviour-preserving:
+ *
+ *  - **A `<ShellPrefsProvider>` is now required for server-side persistence.**
+ *    Without one, `useShellPrefs()` reads empty and drops saves, so column
+ *    config degrades to localStorage-only. All three consumers that render
+ *    `<EntityList>`/`<ResizableTable>` mount the provider.
+ *  - **Prefs and admin defaults resolve independently**, where the raw pair was
+ *    a single `Promise.all`. If the admin default lands while prefs are still
+ *    loading it applies first and the user's own config replaces it a beat
+ *    later, rather than never showing. `useSort` has always behaved this way;
+ *    the two hooks now agree. The precedence that used to be one `if/else if`
+ *    is now the `userSavedRef` guard below plus the order the two effects fire
+ *    in — `tests/columnConfigDefaultsPrecedence.test.tsx` pins both directions.
+ *  - **A failed save is silent here.** The old `useMutation` let a rejected
+ *    `PATCH` reach a consumer's global `MutationCache({ onError })` — the admin
+ *    portal toasted it. The adapter's `save` owns its own failures now, so a
+ *    consumer that wants that toast raises it inside the adapter.
+ *
+ * What it does NOT require is a `<QueryClientProvider>` — it used to, for the
+ * `useMutation`. `useDefaultColumnConfig` falls back to a client the package
+ * owns when no provider is mounted.
+ */
+declare function useColumnConfig(tableId: string, defaultColumns: ColumnDef[]): {
+    orderedColumns: {
+        width: number;
+        key: string;
+        label: string;
+        defaultWidth?: number;
+        minWidth?: number;
+        defaultHidden?: boolean;
+        headerNode?: react__default.ReactNode;
+        sortField?: string;
+    }[];
+    allColumns: {
+        key: string;
+        label: string;
+        hidden: boolean;
+    }[];
+    onResizeStart: (idx: number, e: react__default.MouseEvent) => void;
+    onDragStart: (idx: number) => void;
+    onDragOver: (visIdx: number, e: react__default.DragEvent) => void;
+    onDrop: (_visIdx: number, e: react__default.DragEvent) => void;
+    onDragEnd: () => void;
+    toggleColumn: (key: string) => void;
+    resetColumns: () => void;
+    draggedIdx: number | null;
+    dropGap: number | null;
+};
+
+interface UseInfiniteScrollOptions<T> {
+    /** queryKey segments — arbitrary cache shapes (filters often include booleans,
+     *  dates, undefined). Callers pass their natural filter shape. */
+    queryKey: (string | Record<string, unknown>)[];
+    fetchFn: (params: Record<string, string>) => Promise<PaginatedResponse<T>>;
+    /** Extra query-string params. Undefined values are dropped so axios doesn't
+     *  serialise them as "?key=undefined". */
+    extraParams?: Record<string, string | undefined>;
+    pageSize?: number;
+}
+/**
+ * Wraps TanStack `useInfiniteQuery` with an IntersectionObserver-driven
+ * sentinel so attaching `sentinelRef` to a div near the bottom of a scrollable
+ * container auto-fires `fetchNextPage` as the user scrolls.
+ *
+ * Works inside modal windows too — the observer roots itself on the nearest
+ * scrollable ancestor rather than the viewport.
+ */
+declare function useInfiniteScroll<T>({ queryKey, fetchFn, extraParams, pageSize: _pageSize, }: UseInfiniteScrollOptions<T>): {
+    items: T[];
+    totalCount: number;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    isFetchingNextPage: boolean;
+    hasNextPage: boolean;
+    sentinelRef: react.RefObject<HTMLDivElement>;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<PaginatedResponse<T>, unknown>, Error>>;
+};
+
+/** The part of a column `useSort` reads — `ColumnDef` and `EntityList`'s own
+ *  column both fit.
+ *
+ *  Not `DataTable`: its columns nest inside groups and it offers a sort on
+ *  `sortable`, not on `sortField ?? key`. `DataTableColumn` satisfies this
+ *  interface structurally, so passing one typechecks and then drops sorts the
+ *  table does offer. `DataTable` owns its own sort state through
+ *  `onSortChange`. */
+interface SortableColumn {
+    key: string;
+    sortField?: string;
+}
+/**
+ * Sort-state hook used by list pages. Returns:
+ * - `sort` — current `{ field, direction }`
+ * - `onSort(field)` — toggle direction if same field, else activate asc
+ * - `ordering` — DRF-style string (`'-mid'` for desc, `'mid'` for asc) ready
+ *    to drop into a query-string param.
+ *
+ * Pass `tableId` (the same id the list gives `<ResizableTable>`/`<EntityList>`)
+ * to persist the user's choice alongside their column config. Restore order:
+ * per-user pref (`prefs.sort_{tableId}` via the ShellPrefs adapter) → the
+ * admin-saved default on `/auth/default-columns/{tableId}/` → the page's
+ * `defaultField`/`defaultDir`. localStorage mirrors the last-applied value so
+ * the first render (before async prefs arrive) already uses the last-known
+ * sort instead of flashing the default and refetching. Without `tableId` the
+ * hook is pure in-memory state, exactly as before.
+ *
+ * The admin default is read through `useDefaultColumnConfig`, shared with
+ * `useColumnConfig` so a list page fetches that row once rather than twice
+ * (SG#00590). That probe is a react-query query, but this hook still needs no
+ * `<QueryClientProvider>` in either form: with no provider above it the probe
+ * falls back to a client the package owns (see `useDefaultColumnConfig`), and
+ * the `tableId`-less form issues no request at all, as before.
+ *
+ * Pass `options.columns` (the same array the table gets) and a sort the
+ * columns do not offer is replaced by the page default in `sort` and
+ * `ordering` — a save on a column since given `sortField: ''`, or on a key
+ * whose column now sorts on another `sortField`. Without it that stale save
+ * goes out as `?ordering=` on every open; DRF drops a term it cannot order by,
+ * so the list comes back unsorted for good. Without `columns` — or while the
+ * array is still empty, which is a list page whose columns are not built yet
+ * rather than a table that offers no sort — nothing is checked, as before.
+ */
+declare function useSort(defaultField: string, defaultDir?: 'asc' | 'desc', tableId?: string, options?: {
+    columns?: ReadonlyArray<SortableColumn>;
+}): {
+    sort: SortState;
+    onSort: (field: string) => void;
+    ordering: string;
+};
+
+interface FilterOption {
+    label: string;
+    field: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    searchable?: boolean;
+}
+interface FilterBarProps {
+    filters: FilterOption[];
+    values: Record<string, string>;
+    onChange: (field: string, value: string) => void;
+    onClear: () => void;
+    children?: ReactNode;
+}
+/**
+ * FilterBar — a horizontal row of filter controls. Each filter renders a custom
+ * listbox dropdown or, for long lists, a glass-styled searchable dropdown; a
+ * "Clear filters" button appears when any filter is active. Pair with
+ * `useFilters`.
+ *
+ * The short-list path used to render a native `<select>`, but a native select's
+ * OS popup swallows every key event while open — so list-page hotkeys died
+ * until it closed (BG#00421). PlainFilter is a custom listbox that keeps key
+ * events flowing to the page.
+ */
+declare function FilterBar({ filters, values, onChange, onClear, children }: FilterBarProps): react_jsx_runtime.JSX.Element;
+/** Local filter-state helper: tracks active filter values + derived params. */
+declare function useFilters(): {
+    filterValues: Record<string, string>;
+    setFilter: (field: string, value: string) => void;
+    clearFilters: () => void;
+    filterParams: Record<string, string>;
+};
+
+/**
+ * Shell interaction marks, folded into every perf-log record.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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 beginWindowGesture(kind: 'move' | 'resize'): () => void;
+
+/** The description body for a filed performance report. */
+declare function describePerfReport(report: PerfReport): string;
+/** The attachment. A `File` rather than a `Blob` so the multipart part carries
+ *  the stamped filename the receiving end stores. */
+declare function perfReportFile(report: PerfReport): File;
+
+/**
+ * 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"
+ * regardless of its declared kind.
+ * - `key`   — the identifier rows are de-duplicated/merged on (text-like).
+ * - `price` — a money column (matched by `$`/decimals; totalled with 2 dp).
+ * - `qty`   — a whole-number quantity column.
+ * - `text`  — anything else; never auto-mapped, never totalled.
+ */
+type BulkColumnKind = 'key' | 'price' | 'qty' | 'text';
+interface BulkColumn {
+    key: string;
+    title: string;
+    width?: number;
+    required?: boolean;
+    /**
+     * Hint for CSV auto-mapping and totals. Defaults: the first column is `key`,
+     * every other column is `text`. Set `price`/`qty` to opt a column into
+     * auto-detection and the totals strip.
+     */
+    kind?: BulkColumnKind;
+}
+interface BulkImportGridProps {
+    /** Column definitions. The FIRST column is always the merge key. */
+    columns: BulkColumn[];
+    /** Called with the resolved, de-duplicated rows (one object per row, keyed by column key). */
+    onImport: (rows: Record<string, string>[]) => Promise<void>;
+    /** Called when the user cancels an in-progress mapping/duplicate review. */
+    onCancel: () => void;
+    /** Optional override for the help text shown above the grid. */
+    description?: string;
+    /**
+     * When set, duplicate key values are merged into a single row with their
+     * numeric columns summed, instead of offering keep-first / keep-last / skip.
+     * Use for quantity-based imports where two rows of the same key mean "both" —
+     * never for price imports, where summing prices would be nonsensical.
+     */
+    mergeDuplicates?: boolean;
+}
+/**
+ * Spreadsheet-style bulk entry surface: type, paste, or upload a CSV/TSV, with
+ * automatic column auto-mapping (with a manual mapping fallback) and duplicate
+ * de-duplication (keep-first/last/all/skip, or summed merge in `mergeDuplicates`
+ * mode). Purely presentational — owns local grid/CSV state and reports the
+ * resolved rows via `onImport`; it does no fetching, auth, or persistence.
+ *
+ * Rows are de-duplicated and merged on the FIRST column (the "key"). Declare a
+ * column's `kind` (`price`/`qty`) to opt it into CSV auto-detection and the
+ * totals strip.
+ */
+declare function BulkImportGrid({ columns, onImport, description, mergeDuplicates }: BulkImportGridProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure helpers for reconciling a bulk-import grid (rows of string cells) against
+ * an existing items array, keyed by a designated "key column" (e.g. a part
+ * number, SKU, or code). No app/framework dependencies — usable by any consumer
+ * of {@link BulkImportGrid}.
+ *
+ * Merge rule: a blank cell means "don't touch the original" — only an explicit
+ * value (including "0") replaces what's already there. Existing rows the user
+ * didn't mention in the bulk grid are left untouched. Unknown keys are appended
+ * via the caller-supplied `newItem` factory.
+ */
+type BulkRow = Record<string, string | undefined>;
+interface DuplicateGroup {
+    /** Key value as it appeared in the first occurrence (trimmed, original casing). */
+    key: string;
+    /** Indices into the rows array where this key appears. Length is always >= 2. */
+    rowIndices: number[];
+}
+/**
+ * Find key values that appear more than once within a single bulk-import file.
+ * Match is case-insensitive (consistent with {@link mergeBulkItems}). Blank key
+ * cells are ignored. The caller is expected to surface these to the user before
+ * merge so they can pick a per-group resolution.
+ */
+declare function findDuplicateKeys(rows: BulkRow[], keyRowKey: string): DuplicateGroup[];
+interface BaseItem {
+    [key: string]: unknown;
+}
+interface MergeBulkResult<T> {
+    merged: T[];
+    importedCount: number;
+}
+interface MergeBulkOptions<T extends BaseItem> {
+    /** Raw rows from BulkImportGrid. */
+    rows: BulkRow[];
+    /** Existing items array to merge into. */
+    existing: T[];
+    /**
+     * Mapping from row column key → item field key.
+     * MUST include the key-column mapping (e.g. `{ pn: 'part_number' }`).
+     * Example: `{ pn: 'part_number', qty: 'quantity', price: 'unit_price' }`.
+     */
+    fieldMap: Record<string, string>;
+    /**
+     * The item field that holds the merge key — the value `fieldMap` maps the
+     * grid's key column onto. Existing items are matched against this field
+     * (case-insensitive). Defaults to `'part_number'`.
+     */
+    keyField?: string;
+    /**
+     * Build a brand-new item for a row whose key isn't in `existing`.
+     * `filled` contains only the fields the user actually entered (mapped to
+     * item-field keys via `fieldMap`); supply defaults for anything required
+     * by your item shape.
+     */
+    newItem: (filled: Partial<T>) => T;
+}
+declare function mergeBulkItems<T extends BaseItem>(options: MergeBulkOptions<T>): MergeBulkResult<T>;
+
+interface UndoControlsProps {
+    /** Extra classes for the wrapping row. */
+    className?: string;
+    /**
+     * Set by the shell on the pair it mounts itself — the window footer's, or a
+     * nested provider's. A form's own `<UndoControls />` leaves it unset and
+     * claims the stack, and the shell then mounts nothing for it — so a form
+     * written before the shell did this keeps its pair where it put it, and
+     * shows one rather than two.
+     */
+    auto?: boolean;
+}
+/**
+ * Undo/Redo for the enclosing form, reading the stack from {@link UndoProvider}.
+ *
+ * The shell mounts this pair itself, in the window footer's left slot, for any
+ * window whose form has registered state and whose user may edit it — a form
+ * has nothing to add for the buttons to appear. Mount it by hand only for a
+ * place the footer is not: a section header, a toolbar of a page with no
+ * window footer. 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 —
+ * and nothing while the shell's own pair is showing for the same stack.
+ */
+declare function UndoControls({ className, auto }: UndoControlsProps): react_jsx_runtime.JSX.Element | null;
+
+/** Result of a single health poll. `latencyMs` is optional; when omitted on
+ *  an ok result the indicator simply shows no latency for that poll. */
+interface HealthCheckResult {
+    ok: boolean;
+    latencyMs?: number;
+}
+/** Display fields for the signed-in user shown in the popover's Session
+ *  section. All optional — the indicator derives a sensible name and hides
+ *  the Role row when `role` is empty. Pass `null`/`undefined` for "not
+ *  signed in". */
+interface ServerStatusUser {
+    name?: string;
+    email?: string;
+    /** Secondary label for the Role row (e.g. group names, portal, company).
+     *  Hidden when empty. */
+    role?: string;
+}
+interface ServerStatusIndicatorProps {
+    /**
+     * Performs one health poll and resolves with the outcome. The shell calls
+     * this on mount and on every interval tick. A custom implementation owns
+     * its own timeout/abort. When omitted, the indicator polls `healthUrl`
+     * (default `/api/health/`) with a `requestTimeoutMs` AbortController.
+     */
+    healthCheck?: () => Promise<HealthCheckResult>;
+    /** URL used by the built-in fetcher when no `healthCheck` is supplied. */
+    healthUrl?: string;
+    /** Poll interval in ms. Default 15 000. */
+    pollMs?: number;
+    /** Per-request timeout for the built-in fetcher, in ms. Default 5 000. */
+    requestTimeoutMs?: number;
+    /** Signed-in user's display fields for the Session section. */
+    user?: ServerStatusUser | null;
+    /** Build/version label for the Build section. Defaults to the shell's own
+     *  package version. Pass the consuming app's version here. */
+    version?: string;
+}
+/**
+ * System-tray globe that polls a health check and exposes connection details
+ * in a click-to-open popover. Drop into a taskbar tray alongside the
+ * notification bell; supply `healthCheck` (or `healthUrl`), `user`, and
+ * `version` via a thin per-app wrapper.
+ */
+declare function ServerStatusIndicator({ healthCheck, healthUrl, pollMs, requestTimeoutMs, user, version, }: ServerStatusIndicatorProps): react_jsx_runtime.JSX.Element;
+
+interface ChangePasswordFormProps {
+    /**
+     * Perform the password change. Resolve to indicate success; reject with an
+     * `Error` whose `message` becomes the inline error shown to the user.
+     */
+    onSubmit: (oldPassword: string, newPassword: string) => Promise<void>;
+    /** Called after a successful change — on Done click, or immediately when
+     *  `confirmOnSuccess` is false. */
+    onSuccess?: () => void;
+    /**
+     * Show a success confirmation screen with a Done button after a successful
+     * change. When false, `onSuccess` fires immediately on success. Default true.
+     */
+    confirmOnSuccess?: boolean;
+    /** Minimum length required for the new password. Default 8. */
+    minLength?: number;
+    /** Label for the submit button. Default 'Change Password'. */
+    submitLabel?: string;
+    /** Label for the Done button on the success screen. Default 'Done'. */
+    doneLabel?: string;
+}
+/**
+ * Product-agnostic change-password form. The host supplies `onSubmit` to do the
+ * actual change (e.g. call an API then re-authenticate).
+ */
+declare function ChangePasswordForm({ onSubmit, onSuccess, confirmOnSuccess, minLength, submitLabel, doneLabel, }: ChangePasswordFormProps): react_jsx_runtime.JSX.Element;
+
+interface PdfActionButtonProps {
+    /**
+     * Resolves the PDF bytes. The consumer owns the transport (axios/fetch/etc.)
+     * and any error reporting; returning `null` aborts the action without the
+     * shell surfacing a toast (the consumer is expected to have explained the
+     * failure already).
+     */
+    fetchPdf: () => Promise<Blob | null>;
+    /** Filename used for download and shown in the Preview window (e.g. "Invoice_CI#1234.pdf"). */
+    filename: string;
+    /** Button label. */
+    label?: string;
+    /** Override the default button styling. */
+    className?: string;
+    /** Disabled state. */
+    disabled?: boolean;
+    /**
+     * Optional email handler. When supplied, a "Send by Email" item (with a
+     * divider above it) is added to the menu and an Email button is wired into
+     * the Preview window — both invoked with the already-fetched blob so the
+     * consumer can hand it to its own composer. Omit it to hide email entirely.
+     */
+    onEmail?: (blob: Blob) => void;
+    /**
+     * Optional notification fired after a Preview window has been opened with the
+     * resolved PDF (e.g. to drop a Recent Documents shortcut). Receives the
+     * filename so the consumer can label the entry.
+     */
+    onPreviewOpened?: (filename: string) => void;
+    /**
+     * How to show the Preview. Defaults to the window manager's
+     * `openPage('/preview')`; a routed app without windows (no
+     * `WindowManagerProvider`, so that `openPage` does nothing) passes its own —
+     * a tab, a route or an overlay that mounts the shell's `Preview`.
+     *
+     * It is called where `openPage` would be: after the "LOADING PDF"
+     * placeholder is staged and before the fetch, so the viewer opens on the
+     * placeholder and swaps the document in itself. `onPreviewOpened` is too
+     * late for this: it fires once the document has arrived, so nothing would
+     * show while it loads.
+     */
+    openPreview?: () => void;
+    /** Optional leading icon override for the button (defaults to a document glyph). */
+    icon?: ReactNode;
+    /**
+     * How long to wait for `fetchPdf()` before giving up, in milliseconds.
+     * Defaults to 30 seconds. Pass `0` (or `Infinity`) to wait for ever.
+     *
+     * This exists because a promise that never settles used to leave the Preview
+     * window on its "LOADING PDF" placeholder indefinitely, so a slow document
+     * and a dead one were indistinguishable to the person waiting. Timing out
+     * turns that silence into a stated failure. The request itself is not
+     * cancelled — the consumer owns the transport (see `withTimeout`).
+     */
+    timeoutMs?: number;
+}
+/**
+ * A dropdown PDF button that can Preview the document in the shell's Preview
+ * window, Download it, or (when `onEmail` is supplied) hand the bytes to a
+ * consumer-provided email composer.
+ *
+ * The shell is transport-agnostic: it never fetches the PDF itself. The
+ * consumer injects a `fetchPdf()` resolver (typically wrapping its own HTTP
+ * client) and the shell handles object-URL lifecycle, download, the loading
+ * placeholder in Preview, and success toasts. App concerns (email composer,
+ * recent-documents logging, where the Preview opens) are lifted to the
+ * optional `onEmail` / `onPreviewOpened` / `openPreview` callbacks.
+ */
+declare function PdfActionButton({ fetchPdf, filename, label, className, disabled, onEmail, onPreviewOpened, openPreview, icon, timeoutMs, }: PdfActionButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ShellAuth {
+    /** Returns true if the current user has any of the listed permission codes. */
+    hasAnyPerm: (perms: string[]) => boolean;
+}
+declare function ShellAuthProvider({ value, children }: {
+    value: ShellAuth;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useShellAuth(): ShellAuth;
+
+type EntityFetcher = (endpoint: string, id: string) => Promise<any>;
+declare function ShellEntityFetcherProvider({ value, children, }: {
+    value: EntityFetcher;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Returns the consumer-supplied entity fetcher, or a stub that throws
+ *  on call. Components that fetch entities call this hook eagerly so any
+ *  misconfiguration surfaces synchronously rather than at click-time. */
+declare function useShellEntityFetcher(): EntityFetcher;
+
+/**
+ * INTERNAL stub — bridges legacy `apiClient.get/patch('/auth/me/', ...)` calls
+ * inside the shell to the new <ShellPrefsProvider> contract. This keeps the
+ * package's copied source compiling without rewriting every call site at
+ * once; consumer-supplied prefs flow through `<ShellPrefsProvider>`.
+ *
+ * Outside calls (anything not hitting `/auth/me/`) need the consumer to mount
+ * <ShellEntityFetcherProvider> and wire `entityFetcher` on <WindowManager>.
+ *
+ * When `setShellApiClient` has not been called, HTTP methods resolve with an
+ * empty payload instead of throwing — so consumers without a backend (the
+ * Pages demo, for instance) can still mount the shell. A one-time console
+ * warning surfaces the missing wiring without crashing the app.
+ *
+ * Long-term this file is removed when each call site migrates to
+ * `useShellPrefs()` directly.
+ */
+
+/** Consumer registers their own axios instance — typically the same one
+ *  they use elsewhere. The package only delegates HTTP to this. */
+declare function setShellApiClient(instance: AxiosInstance): void;
+
+/**
+ * Shared task data model — used by the TodoList app, the Pomodoro widget,
+ * and the Calendar app. Stored in `shellPrefs.todo_tasks` (a single array)
+ * so all three views read/write the same source of truth.
+ */
+interface TodoTask {
+    /** Local UUID — stable across renames, used by Pomodoro for active-task pinning. */
+    id: string;
+    name: string;
+    done: boolean;
+    /** Optional deadline, formatted YYYY-MM-DD so it sorts as a string. Drives the Calendar badge. */
+    dueDate?: string;
+    /** Pomodoro estimate (count of focus blocks the user expects to spend). */
+    estimated?: number;
+    /** Pomodoro count completed against this task. */
+    completed?: number;
+    /** Free-text notes — surfaced in the Todo edit drawer. */
+    notes?: string;
+    /** Origin of the task — e.g. 'crm' for tasks backed by a CRM deal/contact. Set by a TodoProvider. */
+    source?: string;
+    /** Short context label shown as a badge (e.g. "Deal: Acme", "Contact: Jane"). Set by a TodoProvider. */
+    contextLabel?: string;
+    /** ISO timestamp — useful for "recently added" sorting. */
+    createdAt: string;
+    /** ISO timestamp — bumped on every local mutation. */
+    updatedAt: string;
+}
+
+/**
+ * A consumer-supplied task backend. Registering one (opt-in) routes every
+ * shell task surface through it instead of the prefs blob. Methods map to/from
+ * the shell's `TodoTask` shape, including the optional `source`/`contextLabel`.
+ */
+interface TodoProvider {
+    list(): Promise<TodoTask[]>;
+    create(input: Partial<Omit<TodoTask, 'id' | 'createdAt' | 'updatedAt'>> & {
+        name: string;
+    }): Promise<TodoTask>;
+    update(id: string, patch: Partial<TodoTask>): Promise<TodoTask>;
+    remove(id: string): Promise<void>;
+}
+/** Register (or clear with `null`) the backend task provider. Opt-in. */
+declare function setShellTodoProvider(next: TodoProvider | null): void;
+
+interface ShellUser {
+    email?: string;
+    first_name?: string;
+    last_name?: string;
+    avatar_url?: string;
+}
+/** Consumer registers user-identity + logout handler once at app startup. */
+declare function setShellAuthBridge(bridge: {
+    user?: ShellUser;
+    logout?: () => void;
+}): void;
+
+/**
+ * Registers Alt+Shift+N (Windows) / Opt+Shift+N (Mac) hotkey to trigger a "New" action.
+ * Uses e.code (physical key) to avoid locale/modifier character issues.
+ * Only fires for the active (frontmost) window, mirroring useEditHotkey — without
+ * the guard every mounted window's hook answered one keypress at once, so with
+ * two or more list windows open Alt+Shift+N fired "New" in all of them.
+ */
+declare function useNewHotkey(callback: () => void): void;
+
+/**
+ * Registers Alt+Shift+E (Windows) / Opt+Shift+E (Mac) hotkey to trigger an "Edit" action.
+ * Uses e.code (physical key) to avoid locale/modifier character issues.
+ * Only fires for the active (frontmost) modal.
+ */
+declare function useEditHotkey(callback: (() => void) | null): void;
+
+/**
+ * Registers a handler for the Cmd+S "save and stay" event dispatched by Modal.
+ * The callback should save the form data WITHOUT closing the modal.
+ *
+ * Fires ONLY for the window the keystroke was aimed at. Modal restricts the
+ * dispatch to the topmost modal, but the event goes to `document`, so without
+ * this match every mounted window's hook answered one keypress — and with two
+ * forms open, a single Cmd+S saved both. Depending on each form's mode that
+ * either PATCHed a background record or CREATEd a brand new one, each with its
+ * own success toast, so the user saw the write and misread which window it came
+ * from.
+ *
+ * The match is on the originating modal's id rather than on
+ * {@link useModalActive}, which asks a different question: "is the frontmost
+ * modal mine". Every nested dialog a form opens pushes itself onto the
+ * activation order, so a form with a child dialog open would read as inactive
+ * and Cmd+S would silently do nothing where it used to save.
+ *
+ * An event with no `detail.modalId` is treated as "for me", so a consumer on a
+ * newer package than the shell that dispatched it keeps working exactly as
+ * before rather than losing Cmd+S entirely.
+ */
+declare function useModalSave(callback: (() => void) | null): void;
+
+/**
+ * Registers a handler for the Alt+Shift+D "save as new / duplicate" event
+ * dispatched by Modal. The callback should save the form data as a NEW record
+ * (ignoring the current ID).
+ *
+ * Window-scoped for the same reason as {@link useModalSave}, and the stakes are
+ * higher here: an unscoped duplicate created a second record from every open
+ * form at once, and one consumer closes its window on success, so a background
+ * window vanished as well.
+ */
+declare function useModalDuplicate(callback: (() => void) | null): void;
+
+/**
+ * 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[];
+}
+
+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.
+     *
+     * A history is only ever dropped when a record actually lands (a slice takes
+     * a value while the baseline settles); a call on a refetch edge where the
+     * form's guard re-seeds nothing leaves the user's edits undoable. Name the
+     * record — `baseline(id)` — and a switch to another record drops the history
+     * even when the new record's values happen to equal the old, so an undo can
+     * never land on the wrong record.
+     *
+     * Name it from the first load on. The first named call has no earlier name
+     * to compare with, so it never drops the history by itself: a switch away
+     * from a record that was baselined bare keeps its history. And a record with
+     * no id yet passes `null`, not `undefined` — `baseline(undefined)` is a bare
+     * call, so `baseline(record?.id)` loses the switch guard on a create route;
+     * write `baseline(record?.id ?? null)`.
+     */
+    baseline: (key?: string | number | null) => void;
+    /** False when the user may not edit this record, so custom UI can hide
+     *  itself the way `UndoControls` does. */
+    enabled: boolean;
+    /** True once the form has registered any state — the window has something
+     *  an Undo could act on, and the shell shows the controls for it. */
+    hasState: 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;
+/**
+ * Tell the enclosing stack whether this record may be edited right now.
+ *
+ * `enabled` is otherwise the provider's own claim (`canEdit`, `perms`), and
+ * the provider `WindowManager` mounts around every window makes none — it
+ * knows nothing about the record inside. A form that does know says so here:
+ *
+ *     useUndoCanEdit(!isLocked);
+ *
+ * and while the value is false the stack records nothing, ⌘Z is left to the
+ * browser, and the footer shows no controls. A nested
+ * `<UndoProvider canEdit={false}>` in the form's JSX says the same thing: it
+ * shadows the stack for its children and forwards the read-only claim to the
+ * stack above it — the one the form's own `useUndoableState` calls, made above
+ * it in the tree, register with. Either form of the claim makes the whole
+ * window read-only; the hook just needs no extra element. `useUndoCanEdit(true)`
+ * is the positive claim: a window that edits in place outside Edit mode asks
+ * the footer for the pair with it.
+ */
+declare function useUndoCanEdit(canEdit: boolean): void;
+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>>];
+
+export { type ActivityKind, type AsyncEnvironment, BLOCKED_PCT_CPU, type BatteryInfo, BehaviorPanel, type BottleneckKind, type BulkColumn, type BulkColumnKind, BulkImportGrid, type BulkImportGridProps, type BulkRow, CancelButton, ChangePasswordForm, type ChangePasswordFormProps, type ChangelogEntry, type ClockCalendarConfig, ColumnDef, CopyButton, Customization, type CustomizationOmitSection, type CustomizationProps, type CustomizationSection, DEV_BANNER_TEXT, Desktop, type DesktopContextMenuItem, type DesktopHostConfig, DesktopHostProvider, DevIndicator, DocFavStar, type DuplicateGroup, type EntityFetcher, EntityList, type EntityListColumn, type EntityListContextAction, type EntityListProps, EntityWindowFallback, type EntityWindowFallbackProps, EntityWindowLoading, EntityWindowState, type EntityWindowStateProps, FilterBar, type FilterOption, type FpsGroup, type HealthCheckResult, ImageAnnotator, type ImageAnnotatorHandle, type ImageAnnotatorProps, LOG_CAP, Layout, type LayoutProps, type LogSummary, MIN_EVENT_SAMPLES, MIN_GROUP_SAMPLES, MODAL_SUBMIT_SELECTOR, type MenuLayer, type MergeBulkOptions, type MergeBulkResult, type MobileAppConfig, Modal, ModalActions, NATIVE_MENU_ATTR, NotificationBell, type NotificationsConfig, PaginatedResponse, PdfActionButton, type PdfActionButtonProps, type PerfEnvironment, type PerfLogRecord, type PerfReading, type PerfReport, PerfStats, type PerfStatsProps, type PlatformHints, ResizableTable, SMOOTH_FPS, SearchConfig, ServerStatusIndicator, type ServerStatusIndicatorProps, type ServerStatusUser, type ShellAuth, ShellAuthProvider, type ShellBranding, type ShellContextKind, ShellContextMenu, type ShellContextMenuProps, type ShellContextTarget, ShellEntityFetcherProvider, type ShellNotification, ShortcutHelp, SortState, type SortableColumn, SoundsPanel, type StagedTarget, StartMenu, type StickyEntityRef, type StickyResolver, SystemPreferences, type SystemPreferencesProps, type SystemPreferencesSection, type TodoProvider, type TodoTask, UndoControls, type UndoControlsApi, type UndoControlsProps, UndoProvider, type UndoProviderProps, type UndoSnapshot, type UndoState, type UndoStep, type UndoableOptions, type Verdict, WidgetManager, WindowCrashedFallback, WindowErrorBoundary, WindowManagerProvider, WindowRegistry, type WindowTarget, type WindowTargetOptions, WindowTitle, appendRecord as appendPerfRecord, applyDevTitle, beginWindowGesture, classifyActivity, classify as classifyPerf, commitExposeHighlight, copyToClipboard, createWindowRegistry, createWindowTarget, describeContextTarget, describeMachine, describePerfReport, exitExposeMode, findDuplicateKeys, getActiveWindowRoute, getExposeHighlight, getWindowPosition, isDevEnv, isInteracting, keepsNativeMenu, markMenuOpen, mergeBulkItems, toCsv as perfLogToCsv, perfReportFile, readEnvironment as readPerfEnvironment, registerModalEscapeInterceptor, requestAsyncEnvironment, requestWindowFront, setExposeHighlight, setShellApiClient, setShellAuthBridge, setShellNavIcons, setShellTodoProvider, setWindowDefaultPosition, setWindowPosition, subscribeExposeHighlight, summariseFrames, summariseLog as summarisePerfLog, toggleExposeMode, useColumnConfig, useDesktopHost, useEditHotkey, useEnclosingModalId, useFilters, useInfiniteScroll, useIsActiveWindow, useModalActive, useModalDuplicate, useModalSave, useNewHotkey, useShellAuth, useShellEntityFetcher, useSort, useTableNav, useUndo, useUndoCanEdit, useUndoable, useUndoableState, useWidgetSettings, useWindowDirty, useWindowManager, useWindowMenuItem, useWindowTarget, useWindowTitle };