@xh/hoist 83.1.0 → 84.0.1

package/docs/coding-conventions.md

@@ -394,20 +394,13 @@ element factory for functional-style rendering:
 
 ```typescript
 // Library/public component — exports both Component and factory
-export const [MyPanel, myPanel] = hoistCmp.withFactory<MyPanelProps>({
-    displayName: 'MyPanel',
-    model: uses(MyPanelModel),
-    className: 'xh-my-panel',
+export const [Grid, grid] = hoistCmp.withFactory<GridProps>({
+    displayName: 'Grid',
+    model: uses(GridModel),
+    className: 'xh-grid',
 
     render({model, className, ...props}, ref) {
-        return frame({
-            className,
-            ref,
-            item: grid({model: model.gridModel}),
-            bbar: toolbar(
-                button({text: 'Refresh', onClick: () => model.refreshAsync()})
-            )
-        });
+        // ... component render implementation
     }
 });
 ```
@@ -417,16 +410,14 @@ which returns only the element factory. Since these components are rendered via
 JSX), the PascalCase React component is not needed:
 
 ```typescript
-// App or impl component — only the factory is used
-const myDetail = hoistCmp.factory<MyDetailProps>({
-    displayName: 'MyDetail',
-    model: uses(MyDetailModel),
+// App component — only the factory is used.
+const tradeDetail = hoistCmp.factory<TradeDetailProps>({
+    displayName: 'TradeDetail',
+    model: uses(TradeDetailModel),
+    className: 'myapp-trade-detail',
 
-    render({model}) {
-        return vbox(
-            label(model.title),
-            grid({model: model.gridModel})
-        );
+    render({model, className}) {
+        // ... component render implementation
     }
 });
 ```
@@ -461,6 +452,16 @@ render({model, className, ...rest}, ref) {
 Always set `displayName` on components. It appears in React DevTools and error messages. It should
 match the PascalCase export name.
 
+### `className`
+
+Define a base CSS class in the component spec rather than hardcoding it inside the render function.
+The framework automatically merges the spec's base class with any `className` passed by callers, so
+every component consistently supports CSS class overrides without manual merging in render. The
+merged value is provided to `render()` via props — apply it to the component's root element.
+
+The `xh-` prefix is reserved for Hoist library components; applications should standardize on their
+own app-specific prefix.
+
 ### Element Factories vs JSX
 
 Hoist strongly prefers element factory calls over JSX. Factories are functions that take a config
@@ -607,6 +608,13 @@ Public APIs use TSDoc comments (`/** ... */`). TSDoc syntax is checked by ESLint
 loadData(rawData: PlainObject[], rawSummaryData?: PlainObject) { ... }
 ```
 
+### Avoid Unicode in Code Comments
+
+Use plain ASCII in code comments and JSDoc. In particular, use ` - ` (spaced hyphen) rather
+than em dashes (`—`) for parenthetical asides. Unicode characters can cause encoding issues with
+tooling (e.g. grep, MCP tools) and offer no benefit in a monospace code context. Em dashes are
+fine in prose-style `.md` documentation where they render naturally.
+
 ### Observable Annotation Comments
 
 When a property's observable behavior is significant to callers, annotate it in a comment:

package/docs/doc-registry.json

@@ -48,8 +48,16 @@
             "title": "Data Layer",
             "mcpCategory": "package",
             "viewerCategory": "core",
-            "description": "Observable data layer with filtering, validation, and aggregation.",
-            "keywords": ["Store", "StoreRecord", "Field", "Filter", "FilterChooserModel", "FilterFieldSpec", "Cube", "View", "tree data", "loadData", "processRawData"]
+            "description": "Observable data layer with Store, Field, filtering, validation, and tree data.",
+            "keywords": ["Store", "StoreRecord", "Field", "Filter", "FilterChooserModel", "FilterFieldSpec", "tree data", "loadData", "processRawData"]
+        },
+        {
+            "id": "data/cube/README.md",
+            "title": "Cube Aggregation",
+            "mcpCategory": "package",
+            "viewerCategory": "core",
+            "description": "Client-side OLAP-style aggregation with dimensions, measures, Views, and Queries.",
+            "keywords": ["Cube", "CubeField", "View", "Query", "QueryConfig", "aggregator", "dimension", "measure", "SUM", "AVG", "includeRoot", "includeLeaves", "createView"]
         },
         {
             "id": "svc/README.md",
@@ -137,7 +145,7 @@
             "mcpCategory": "package",
             "viewerCategory": "desktop",
             "description": "Desktop-specific components and app container.",
-            "keywords": ["desktop components", "Blueprint wrappers", "Select", "DateInput", "NumberInput", "TextArea", "Picker", "Checkbox", "SwitchInput", "RadioInput", "Slider", "CodeInput", "JsonInput", "LeftRightChooser", "dropdown"]
+            "keywords": ["desktop components", "Blueprint wrappers", "dialog", "modal", "toolbar", "Select", "DateInput", "NumberInput", "TextArea", "Picker", "Checkbox", "SwitchInput", "RadioInput", "Slider", "CodeInput", "JsonInput", "LeftRightChooser", "dropdown"]
         },
         {
             "id": "mobile/README.md",
@@ -360,7 +368,7 @@
             "title": "Changelog Format",
             "mcpCategory": "devops",
             "viewerCategory": "devops",
-            "description": "CHANGELOG entry format conventions and section headers.",
+            "description": "Conventions for writing and reviewing CHANGELOG entries in the hoist-react library CHANGELOG — section headers, voice/tense, difficulty ratings, breaking changes, libraries.",
             "keywords": ["changelog", "CHANGELOG", "format", "conventions", "release notes", "versioning", "breaking changes", "upgrade difficulty", "section headers", "entry structure"]
         },
         {
@@ -369,7 +377,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v72.x to v73.0.1. Low difficulty — hoist-core >= 31, makeObservable enforcement, ESLint 9.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v73", "v72", "makeObservable", "eslint", "admin", "commitOnChange"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v73", "v72"]
         },
         {
             "id": "docs/upgrade-notes/v74-upgrade-notes.md",
@@ -377,7 +385,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v73.x to v74.1.2. Low difficulty — ViewManagerModel.settleTime removal, ChartModel.showContextMenu replaced.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v74", "v73", "settleTime", "showContextMenu", "contextMenu", "ViewManager", "ChartModel"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v74", "v73", "settleTime", "showContextMenu"]
         },
         {
             "id": "docs/upgrade-notes/v75-upgrade-notes.md",
@@ -385,7 +393,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v74.x to v75.0.1. Low difficulty — removed deprecated APIs, Cube View row data changes.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v75", "v74", "deprecation", "ViewRowData", "cube"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v75", "v74", "ViewRowData"]
         },
         {
             "id": "docs/upgrade-notes/v76-upgrade-notes.md",
@@ -393,7 +401,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v75.x to v76.0.0. Medium difficulty — AG Grid v31→v34, new module registration.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v76", "v75", "ag-grid", "ag grid", "module registration", "groupRowRenderer"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v76", "v75", "groupRowRenderer"]
         },
         {
             "id": "docs/upgrade-notes/v77-upgrade-notes.md",
@@ -401,7 +409,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v76.x to v77.1.1. Medium difficulty — Highcharts v12, XSS protection API rename.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v77", "v76", "highcharts", "xss", "enableXssProtection"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v77", "v76", "disableXssProtection"]
         },
         {
             "id": "docs/upgrade-notes/v78-upgrade-notes.md",
@@ -409,7 +417,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v77.x to v78.0.0. Trivial difficulty.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v78", "v77", "setColumnState"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v78", "v77"]
         },
         {
             "id": "docs/upgrade-notes/v79-upgrade-notes.md",
@@ -417,7 +425,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v78.x to v79.0.0. Medium difficulty.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v79", "v78", "Blueprint 6", "moduleResolution"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v79", "v78"]
         },
         {
             "id": "docs/upgrade-notes/v80-upgrade-notes.md",
@@ -425,7 +433,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v79.x to v80.0.0. Low difficulty.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v80", "v79", "FormField", "appLoadObserver"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v80", "v79", "appLoadModel"]
         },
         {
             "id": "docs/upgrade-notes/v81-upgrade-notes.md",
@@ -433,7 +441,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v80.x to v81.0.2. Low difficulty.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v81", "v80", "Panel CSS", "BpCard"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v81", "v80"]
         },
         {
             "id": "docs/upgrade-notes/v82-upgrade-notes.md",
@@ -441,7 +449,7 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v81.x to v82.0.0. Low difficulty.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v82", "v81", "Picker", "DashCanvas", "MCP", "Filter"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v82", "v81", "xh-popup--framed"]
         },
         {
             "id": "docs/upgrade-notes/v83-upgrade-notes.md",
@@ -449,7 +457,15 @@
             "mcpCategory": "devops",
             "viewerCategory": "upgrade",
             "description": "Upgrade guide from v82.x to v83.0.0. Low difficulty.",
-            "keywords": ["upgrade", "migration", "breaking changes", "v83", "v82", "TraceService", "tracing", "OTEL", "static defaults", "GridModel", "downloadBlob", "downloadViaUrl", "downloadjs", "SegmentedControl", "CheckboxButton"]
+            "keywords": ["upgrade", "migration", "breaking changes", "v83", "v82", "downloadjs"]
+        },
+        {
+            "id": "docs/upgrade-notes/v84-upgrade-notes.md",
+            "title": "v84 Upgrade Notes",
+            "mcpCategory": "devops",
+            "viewerCategory": "upgrade",
+            "description": "Upgrade guide from v83.x to v84.0.0. Low difficulty.",
+            "keywords": ["upgrade", "migration", "breaking changes", "v84", "v83", "getClassName"]
         }
     ]
 }

package/docs/planning/docs-roadmap-log.md

@@ -503,3 +503,14 @@
   - Added Quick Reference entry for "Customize colors, fonts, spacing, or theme"
   - Removed `/styles/` from "Other Packages" paragraph (now has a dedicated README)
 - Added `styles` entry to `mcp/data/doc-registry.ts` with CSS/theme/BEM keywords
+
+### 2026-04-14
+- Split Cube documentation out of `data/README.md` into dedicated `data/cube/README.md`:
+  - Expanded querying section with patterns for grand totals (`includeRoot`), leaf drill-down
+    (`includeLeaves`), programmatic leaf access (`provideLeaves`), flat aggregation, dynamic
+    query updates (`updateQuery`/`setFilter`), and one-shot `executeQuery()` usage
+  - Added table of contents, overview with class table, and Related Packages section
+  - Data README retains a brief pointer to the Cube doc
+- Updated `docs/README.md` index: added `/data/cube/` to Quick Reference and Core Framework table
+- Added `data/cube/README.md` entry to `docs/doc-registry.json`
+- Added `/data/cube/` entry to `docs/planning/docs-roadmap.md` Priority 1 table

package/docs/planning/docs-roadmap.md

@@ -15,6 +15,7 @@ is essential for working effectively with any part of hoist-react.
 | `/` (root) | 1 | AGENTS.md provides AI-focused project guidance | [Done](../../AGENTS.md) |
 | `/core/` | 48 | HoistBase, HoistModel, HoistService, XH singleton, component factory | [Done](../../core/README.md) |
 | `/data/` | 45 | Store, StoreRecord, Field, Filter, validation - data layer infrastructure | [Done](../../data/README.md) |
+| `/data/cube/` | 10 | Cube aggregation engine - dimensions, measures, Views, Queries | [Done](../../data/cube/README.md) |
 | `/svc/` | 20 | Services architecture and built-in services (Fetch, Config, Pref, etc.) | [Done](../../svc/README.md) |
 
 ## Priority 2 - Component System

package/docs/upgrade-notes/v84-upgrade-notes.md

@@ -0,0 +1,136 @@
+# Hoist React v84 Upgrade Notes
+
+> **From:** v83.x → v84.0.0 | **Released:** 2026-04-15 | **Difficulty:** 🟢 LOW
+
+## Overview
+
+Hoist React v84 is a major release paired with hoist-core v38. The headline additions are
+FontAwesome v7, an icon-based `Spinner` replacement, client-side span sampling for `TraceService`,
+and a new typed `defaults` mechanism for `hoistCmp` components.
+
+The most significant app-level impacts are:
+
+- **`hoist-core >= 38.0` required** — paired major release
+- **`getClassName()` removed** — unlikely to affect apps (no known usage), but check imports
+- **FontAwesome v7** — visual tweaks to icons; no app changes expected
+
+## Prerequisites
+
+Before starting, ensure:
+
+- [ ] Running hoist-react v83.x
+- [ ] **hoist-core** upgraded to >= v38.0 (**required** — paired major release)
+
+## Upgrade Steps
+
+### 1. Update `hoistCoreVersion` in `gradle.properties`
+
+Hoist React v84 **requires** hoist-core >= v38.0.
+
+**File:** `gradle.properties`
+
+Before:
+```properties
+hoistCoreVersion=37.0.2
+```
+
+After:
+```properties
+hoistCoreVersion=38.0.0
+```
+
+### 2. Update `package.json`
+
+Bump hoist-react to v84.
+
+**File:** `package.json`
+
+Before:
+```json
+"@xh/hoist": "~83.1.0"
+```
+
+After:
+```json
+"@xh/hoist": "~84.0.0"
+```
+
+Then run `yarn install` or `npm install` to update dependencies.
+
+### 3. Remove `getClassName` Import (if applicable)
+
+The `getClassName()` utility has been removed from `@xh/hoist/utils/react`. This function had no
+remaining usages in the framework, and no known app usages. If your app imported it directly, use
+the `className` spec field on `hoistCmp.factory()` / `hoistCmp.withFactory()` instead — it handles
+base class merging automatically.
+
+**Find affected files:**
+```bash
+grep -rE "getClassName.*from '@xh/hoist" client-app/src/
+```
+
+Note: apps that define their own local `getClassName` helpers (not imported from `@xh/hoist`) are
+not affected.
+
+### 4. Review FontAwesome v7 Icon Changes (visual only)
+
+FontAwesome has been updated from v6 to v7. All previously supported icons remain available. The
+upgrade brings subtle visual tweaks and performance optimizations — no API changes are required.
+
+Review any areas of your app where precise icon sizing or spacing is critical, as minor visual
+adjustments to individual glyphs are possible across major FA versions.
+
+If your app depends on `@fortawesome/free-brands-svg-icons` (for brand icons like GitHub, Slack,
+etc.), consider updating it to v7 as well to keep icon versions consistent:
+
+```json
+"@fortawesome/free-brands-svg-icons": "^7.2.0"
+```
+
+### 5. Migrate Deprecated Static Properties to `static defaults` (if not done in v83)
+
+If you have not yet migrated from the deprecated ad-hoc static properties on `GridModel`,
+`ChartModel`, `ExceptionHandler`, and `FetchService`, do so now. These were deprecated in v83 and
+are scheduled for removal in v85. See the
+[v83 upgrade notes](./v83-upgrade-notes.md#3-migrate-deprecated-static-properties-to-static-defaults-recommended)
+for detailed before/after examples.
+
+**Find affected files:**
+```bash
+grep -rE "GridModel\.(DEFAULT_AUTOSIZE_MODE|DEFAULT_RESTORE_DEFAULTS_WARNING|defaultContextMenu)|ChartModel\.defaultContextMenu|ExceptionHandler\.(REDACT_PATHS|ALERT_TYPE|TOAST_PROPS)|FetchService\.(autoGenCorrelationIds|genCorrelationId|correlationIdHeaderKey)" client-app/src/
+```
+
+### 6. Migrate Deprecated Filter Utilities (if not done in v83)
+
+If you have not yet migrated from the deprecated standalone filter utilities (`withFilterByField`,
+`withFilterByKey`, `replaceFilterByKey`, `withFilterByTypes`), do so now. These were deprecated
+in v82 and are scheduled for removal in v85. See the
+[v82 upgrade notes](./v82-upgrade-notes.md#5-migrate-deprecated-filter-utilities) for detailed
+before/after examples.
+
+**Find affected files:**
+```bash
+grep -rE "withFilterByField|withFilterByKey|replaceFilterByKey|withFilterByTypes" client-app/src/
+```
+
+## Verification Checklist
+
+After completing all steps:
+
+- [ ] `hoistCoreVersion` in `gradle.properties` is >= 38.0.0
+- [ ] `yarn install` / `npm install` completes without errors
+- [ ] `yarn lint` / `npm run lint` passes (or only pre-existing warnings remain)
+- [ ] `npx tsc --noEmit` passes
+- [ ] Application loads without console errors
+- [ ] No `getClassName` imports from hoist-react remain:
+  `grep -rE "getClassName.*from '@xh/hoist" client-app/src/`
+- [ ] Icons render correctly throughout the app (spot-check grids, toolbars, menus)
+- [ ] Spinner renders correctly on loading screens
+- [ ] No deprecated static property warnings in console:
+  `grep -rE "DEFAULT_AUTOSIZE_MODE|DEFAULT_RESTORE_DEFAULTS_WARNING|defaultContextMenu|REDACT_PATHS|ALERT_TYPE|TOAST_PROPS" client-app/src/`
+- [ ] No deprecated filter utilities remain:
+  `grep -rE "withFilterByField|withFilterByKey|replaceFilterByKey|withFilterByTypes" client-app/src/`
+
+## Reference
+
+- [Toolbox on GitHub](https://github.com/xh/toolbox) — canonical example of a Hoist app

package/docs/version-compatibility.md

@@ -54,6 +54,7 @@ Verified against both hoist-react and hoist-core changelogs.
 
 | hoist-react | Min Core Required | Recommended Core | Max Core Tested | Notes | Upgrade |
 |---|---|---|---|---|---|
+| 84.0 | 38.0 | | 38.0 | Span sampling, OTEL tag alignment, log level overrides | [Notes](./upgrade-notes/v84-upgrade-notes.md) |
 | 83.0 | 37.0 | | 37.0 | OTEL tracing, static defaults, metrics publishing | [Notes](./upgrade-notes/v83-upgrade-notes.md) |
 | 82.0 | -- | 36.3 | 36.3 | Admin Metrics tab | [Notes](./upgrade-notes/v82-upgrade-notes.md) |
 | 81.0 | 36.1 | | 36.2 | Efficient identity init | [Notes](./upgrade-notes/v81-upgrade-notes.md) |
@@ -108,6 +109,7 @@ to find the minimum hoist-react version for a given core release.
 
 | hoist-core | Min hoist-react | Notes |
 |---|---|---|
+| 38.0 | 84.0 | Span sampling, OTEL tag alignment, log level overrides |
 | 37.0 | 83.0 | OTEL tracing, metrics publishing |
 | 36.3 | 82.0 recommended | Admin Metrics tab |
 | 36.1 | 81.0 | Efficient identity init |

package/format/FormatDate.ts

@@ -30,7 +30,7 @@ export interface DateFormatOptions extends FormatOptions<DateLike> {
 
     /**
      * A MomentJs format string. Wrap literal text in square brackets to prevent
-     * interpretation as format tokens — e.g. `'[today at] h:mma'`.
+     * interpretation as format tokens - e.g. `'[today at] h:mma'`.
      */
     fmt?: string;
 }
@@ -99,19 +99,19 @@ export function fmtTime(v: DateLike, opts?: DateFormatOptions | string) {
 export interface CompactDateFormatOptions extends FormatOptions<DateLike> {
     /**
      * Format for date matching current day, defaults to 'hh:mma' for dates, 'MMM D' for
-     * LocalDates. Wrap literal text in square brackets — e.g. `'[today]'` or `'[today at] h:mma'`.
+     * LocalDates. Wrap literal text in square brackets - e.g. `'[today]'` or `'[today at] h:mma'`.
      */
     sameDayFmt?: string;
 
     /**
      * Format for dates within the number of months specified by the distantThreshold, defaults
-     * to 'MMM D'. Wrap literal text in square brackets — e.g. `'[recent]'`.
+     * to 'MMM D'. Wrap literal text in square brackets - e.g. `'[recent]'`.
      */
     nearFmt?: string;
 
     /**
      * Format for dates beyond number of months specified by the distantThreshold, defaults to
-     * 'YYYY-MM-DD'. Wrap literal text in square brackets — e.g. `'[older]'`.
+     * 'YYYY-MM-DD'. Wrap literal text in square brackets - e.g. `'[older]'`.
      */
     distantFmt?: string;
 

package/icon/Icon.ts

@@ -278,6 +278,9 @@ export const Icon = {
     circle(p?: IconProps) {
         return Icon.icon({...p, iconName: 'circle'});
     },
+    circleNotch(p?: IconProps) {
+        return Icon.icon({...p, iconName: 'circle-notch'});
+    },
     clipboard(p?: IconProps) {
         return Icon.icon({...p, iconName: 'clipboard'});
     },
@@ -663,6 +666,12 @@ export const Icon = {
     spinner(p?: IconProps) {
         return Icon.icon({...p, iconName: 'spinner'});
     },
+    spinnerScale(p?: IconProps) {
+        return Icon.icon({...p, iconName: 'spinner-scale'});
+    },
+    spinnerThird(p?: IconProps) {
+        return Icon.icon({...p, iconName: 'spinner-third'});
+    },
     square(p?: IconProps) {
         return Icon.icon({...p, iconName: 'square'});
     },

package/icon/README.md

@@ -1,10 +1,10 @@
 # Icon
 
-Hoist's icon system provides a factory-based API for rendering [FontAwesome](https://fontawesome.com/)
-Pro icons throughout an application. Rather than importing individual FA icon definitions in each
-file that uses them, applications use the `Icon` singleton — a centralized catalog of 150+ direct
-icon factories and ~40 semantic aliases, all pre-registered with the FA library in four weight
-variants (regular, solid, light, thin).
+Hoist's icon system provides a factory-based API for
+rendering [FontAwesome](https://fontawesome.com/) Pro icons throughout an application. Rather than
+importing individual FA icon definitions in each file that uses them, applications use the `Icon`
+singleton — a centralized catalog of 150+ direct icon factories and ~40 semantic aliases, all
+pre-registered with the FA library in four weight variants (regular, solid, light, thin).
 
 ## Overview
 
@@ -103,6 +103,45 @@ Icon.star({rotation: 90})        // rotated 90 degrees
 Icon.warning({bounce: true})     // bouncing warning
 ```
 
+### Spinner Component
+
+The `Spinner` component (`cmp/spinner/`) renders an animated FA icon for use by `Mask` and
+`LoadingIndicator`. The rotation animation is applied via Hoist-owned CSS (`@keyframes xh-spin`
+on `.xh-spinner`) rather than FA's animation props. This ensures the spinner remains functional
+when the OS-level `prefers-reduced-motion` preference is enabled (FA disables all its animations
+in that case) and keeps performance predictable in remote desktop environments such as Citrix.
+
+Spinner ships with several pre-registered icon choices - `faSpinnerThird`, `faCircleNotch`, and
+`faSpinnerScale` - all available in all four weight variants. The default icon and prefix can be
+configured globally via `Spinner.defaults`, typically set in an app's `Bootstrap.ts`:
+
+```typescript
+import {Spinner} from '@xh/hoist/cmp/spinner';
+
+// Override icon and/or weight globally
+Spinner.defaults.iconName = 'circle-notch';
+Spinner.defaults.prefix = 'far';
+```
+
+| Default                        | Type              | Default           | Description                  |
+|--------------------------------|-------------------|-------------------|------------------------------|
+| `Spinner.defaults.iconName`    | `IconName`        | `'spinner-third'` | FA icon name for the spinner |
+| `Spinner.defaults.prefix`      | `HoistIconPrefix` | `'fal'`           | FA icon weight/prefix        |
+| `Spinner.defaults.usePng`      | `boolean`         | `false`           | Fall back to animated PNG    |
+
+Per-instance overrides can be passed as props to `spinner()` or via `LoadingIndicator`'s `spinner`
+prop, which accepts either `true` (use defaults) or a `SpinnerProps` object:
+
+```typescript
+loadingIndicator({
+    bind: myTask,
+    spinner: {iconName: 'circle-notch'}
+})
+```
+
+A legacy PNG fallback is retained for environments where even CSS animations may be problematic.
+Set `Spinner.defaults.usePng = true` globally to revert to the original animated PNG behavior.
+
 ### Weight Variants
 
 ```typescript
@@ -191,16 +230,16 @@ else that accepts an icon element.
 
 ## IconProps Reference
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `iconName` | `IconName` | FA icon name (e.g. `'check'`, `'gear'`). Required for `Icon.icon()`, provided automatically by named factories |
-| `prefix` | `HoistIconPrefix` | Weight variant: `'far'` (regular, default), `'fas'` (solid), `'fal'` (light), `'fat'` (thin), `'fab'` (brands) |
-| `intent` | `Intent` | Applies `xh-intent-{intent}` CSS class for semantic coloring |
-| `title` | `string` | Tooltip text rendered as SVG `<title>` |
-| `size` | `string` | FA size: `'2xs'` through `'10x'` |
-| `asHtml` | `boolean` | Return raw SVG string instead of React element |
-| `className` | `string` | Additional CSS class(es) |
-| `omit` | `Thunkable<boolean>` | Skip rendering this icon when true |
+| Prop        | Type                 | Description                                                                                                    |
+|-------------|----------------------|----------------------------------------------------------------------------------------------------------------|
+| `iconName`  | `IconName`           | FA icon name (e.g. `'check'`, `'gear'`). Required for `Icon.icon()`, provided automatically by named factories |
+| `prefix`    | `HoistIconPrefix`    | Weight variant: `'far'` (regular, default), `'fas'` (solid), `'fal'` (light), `'fat'` (thin), `'fab'` (brands) |
+| `intent`    | `Intent`             | Applies `xh-intent-{intent}` CSS class for semantic coloring                                                   |
+| `title`     | `string`             | Tooltip text rendered as SVG `<title>`                                                                         |
+| `size`      | `string`             | FA size: `'2xs'` through `'10x'`                                                                               |
+| `asHtml`    | `boolean`            | Return raw SVG string instead of React element                                                                 |
+| `className` | `string`             | Additional CSS class(es)                                                                                       |
+| `omit`      | `Thunkable<boolean>` | Skip rendering this icon when true                                                                             |
 
 ## Serialization
 
@@ -258,15 +297,14 @@ packages — don't reach for a different library.
 
 ### Referencing Icons From the Wrong FontAwesome Version
 
-FontAwesome updates frequently and adds new icons with each release. When browsing the
-FA site to find an icon for your app, use
-the version picker to filter results to the version Hoist currently depends on (check
-`@fortawesome/pro-regular-svg-icons` in `package.json`). Attempting to import an icon that only
-exists in a newer FA version will fail at build time. Hoist endeavors to keep its FA dependency up
-to date, but always verify the version before spending time wiring up a new icon.
+FontAwesome updates frequently and adds new icons with each release. When browsing the FA site to
+find an icon for your app, use the version picker to filter results to the version Hoist currently
+depends on (check `@fortawesome/pro-regular-svg-icons` in `package.json`). Attempting to import an
+icon that only exists in a newer FA version will fail at build time. Hoist endeavors to keep its FA
+dependency up to date, but always verify the version before spending time wiring up a new icon.
 
 * [FA icon search (latest version)](https://fontawesome.com/search?ip=classic&s=regular)
-* [FA icon search (v6)](https://fontawesome.com/v6/search?ip=classic&s=regular)
+* [FA icon search (v7)](https://fontawesome.com/v7/search?ip=classic&s=regular)
 
 ### Using Brand Icons Without Registration
 
@@ -276,6 +314,8 @@ with Hoist by default.
 
 ## Related Packages
 
+- [`/cmp/spinner/`](../cmp/spinner/) — Spinner component renders an animated FA icon, configurable
+  via static defaults on the `Spinner` class
 - [`/desktop/`](../desktop/README.md) — Desktop components use icons extensively in buttons,
   toolbars, menus, and grid columns
 - [`/desktop/cmp/dash/`](../desktop/cmp/dash/README.md) — DashContainer uses icon serialization