@xh/hoist 83.0.1 → 83.1.0

package/cmp/treemap/TreeMapModel.ts

@@ -14,26 +14,6 @@ import {throwIf, withDefault} from '@xh/hoist/utils/js';
 import {ReactNode} from 'react';
 import {cloneDeep, get, isEmpty, isFinite, max, set, sortBy, sumBy, unset} from 'lodash';
 
-/**
- * Core Model for a TreeMap.
- *
- * You should specify the TreeMap's data store, in addition to which StoreRecord fields should be
- * mapped to label (a node's display name), value (a node's size), and heat (a node's color).
- *
- * Can also (optionally) be bound to a GridModel. This will enable selection syncing and
- * expand / collapse syncing for GridModels in `treeMode`.
- *
- * Supports any Highcharts TreeMap algorithm ('squarified', 'sliceAndDice', 'stripes' or 'strip').
- *
- * Node colors are normalized to a 0-1 range and mapped to a colorAxis via the following colorModes:
- * 'linear' distributes normalized color values across the colorAxis according to the heatField.
- * 'wash' ignores the intensity of the heat value, applying a single positive and negative color.
- * 'none' will ignore the colorAxis, and instead use the neutral color.
- *
- * Color customization can be managed by setting colorAxis stops via the `highchartsConfig`.
- *
- * @see https://www.highcharts.com/docs/chart-and-series-types/treemap for Highcharts config options
- */
 export interface TreeMapConfig {
     /** A store containing records to be displayed. */
     store?: Store;
@@ -117,6 +97,25 @@ export interface TreeMapModelDefaults {
     maxNodes?: number;
 }
 
+/**
+ * Core Model for a TreeMap, backed by a data Store with fields mapped to each node's label
+ * (display name), value (size), and heat (color).
+ *
+ * Can optionally bind to a GridModel to enable selection and expand/collapse syncing for
+ * GridModels in `treeMode`.
+ *
+ * Supports Highcharts TreeMap algorithms: 'squarified', 'sliceAndDice', 'stripes', and 'strip'.
+ *
+ * Node colors are normalized to a 0-1 range and mapped to a colorAxis. The `colorMode` config
+ * controls how:
+ * - 'linear' — distributes values across the colorAxis according to the heatField.
+ * - 'wash' — ignores heat intensity, applying a single positive/negative color.
+ * - 'none' — ignores the colorAxis entirely, using the neutral color.
+ *
+ * Color customization can be managed by setting colorAxis stops via `highchartsConfig`.
+ * See {@link https://www.highcharts.com/docs/chart-and-series-types/treemap} for Highcharts
+ * TreeMap config options.
+ */
 export class TreeMapModel extends HoistModel {
     /** App-level defaults for TreeMapModel. Instance config takes precedence. */
     static defaults: TreeMapModelDefaults = {

package/core/HoistComponent.ts

@@ -108,34 +108,32 @@ export type ComponentConfig<P extends HoistProps> =
 let cmpIndex = 0; // index for anonymous component dispay names
 
 /**
- * Hoist utility for defining functional components. This is the primary method for creating
- * components for use in Hoist applications. Accepts either a render function (directly) or a
- * configuration object to specify that function and additional options, as described below.
+ * The primary entry point for defining Hoist components — functional React components enhanced
+ * with MobX reactivity and integrated model support.
  *
- * The primary additional config option is `model`. It specifies how a backing HoistModel will be
- * provided to / created by this component and if the component should publish its model to any
- * subcomponents via context.
+ * Accepts a configuration object (or a bare render function) and returns a React functional
+ * component. The `model` config is the key option: use {@link creates} to have the component
+ * create and own its backing model, {@link uses} to source a model from props or context, or
+ * `false` for simple components with no model. Defaults to `uses('*')` if not specified.
  *
- * By default, this utility wraps the returned component in the MobX 'observer' HOC, enabling
- * MobX-powered reactivity and auto-re-rendering of observable properties read from models and
- * any other sources of observable state.
+ * Components are wrapped in the MobX `observer` HOC by default, enabling automatic re-rendering
+ * when observable state read during render changes.
  *
- * Forward refs {@link https://reactjs.org/docs/forwarding-refs.html} are supported by specifying a
- * render function that accepts two arguments. In that case, the second arg will be considered a
- * ref, and this utility will apply `React.forwardRef` as required.
+ * Forward refs ({@link https://reactjs.org/docs/forwarding-refs.html}) are supported by
+ * specifying a render function with two arguments — the second is treated as a ref, and
+ * `React.forwardRef` is applied automatically.
  *
- * @param config - specification object, or a render function defining the component.
- * @returns a functional React Component for use within Hoist apps.
- *
- * @see hoistCmp - a shorthand alias to this function.
+ * Most components should be defined via one of two convenience methods rather than calling
+ * this function directly:
+ * - `hoistCmp.factory()` — returns an element factory (the standard pattern for app components).
+ * - `hoistCmp.withFactory()` — returns a `[Component, factory]` pair (the standard pattern for
+ *    library components that need to export both).
  *
- * This function also has several related functions
+ * See `core/README.md` for full documentation on component configuration, model specs, and
+ * context lookup behavior.
  *
- *   - `hoistCmp.factory` - return an elementFactory for a newly defined Component.
- *           instead of the Component itself.
- *
- *   - `hoistCmp.withFactory` - return a 2-element list containing both the newly
- *          defined Component and an elementFactory for it.
+ * @param config - specification object, or a render function defining the component.
+ * @returns a functional React Component for use within Hoist apps.
  */
 export function hoistCmp<M extends HoistModel>(
     config: ComponentConfig<DefaultHoistProps<M>>

package/core/load/LoadSpec.ts

@@ -8,26 +8,6 @@
 import {PlainObject} from '../types/Types';
 import {LoadSupport} from './';
 
-/**
- * Object describing a load/refresh request in Hoist.
- *
- * Instances of this class are created within the public APIs provided by {@link LoadSupport}
- * and are passed to subclass (i.e. app-level) implementations of `doLoadAsync()`.
- *
- * Application implementations of `doLoadAsync()` can consult this object's flags. Of particular
- * interest are {@link isStale} and {@link isObsolete}, which implementations can read after any
- * async calls return to determine if a newer, subsequent load has already been requested.
- *
- * In addition, `doLoadAsync()` implementations should typically pass along this object to any
- * calls they make to `loadAsync()` on other objects + all calls to {@link FetchService} APIs.
- *
- * Note that Hoist's exception handling and activity tracking will consult the {@link isAutoRefresh}
- * flag on specs passed to their calls to automatically adjust their behavior (e.g. not showing an
- * exception dialog on error, not tracking background refresh activity).
- *
- * @see LoadSupport
- */
-
 export type LoadSpecConfig = {
     /** True if triggered by a refresh request (automatic or user-driven). */
     isRefresh?: boolean;
@@ -37,6 +17,25 @@ export type LoadSpecConfig = {
     meta?: PlainObject;
 };
 
+/**
+ * Immutable descriptor for a load/refresh request, passed to `doLoadAsync()` implementations.
+ *
+ * Instances are created automatically by {@link LoadSupport} when `loadAsync()`,
+ * `refreshAsync()`, or `autoRefreshAsync()` are called. Application code should not construct
+ * LoadSpec instances directly.
+ *
+ * Within `doLoadAsync()`, check {@link isStale} after any async call to determine if a newer
+ * load has already been requested — if so, return early to avoid applying outdated results.
+ * Check {@link isAutoRefresh} to adjust behavior for background refreshes (e.g. skip expensive
+ * operations, avoid user-facing error dialogs).
+ *
+ * Pass this object along to any nested `loadAsync()` calls and to all {@link FetchService}
+ * requests. Hoist's exception handling and activity tracking consult the LoadSpec to
+ * automatically suppress error dialogs and skip tracking for auto-refresh operations.
+ *
+ * @see LoadSupport
+ * @see HoistModel.doLoadAsync
+ */
 export class LoadSpec {
     /** True if triggered by a refresh request (automatic or user-driven). */
     isRefresh: boolean;

package/data/impl/RecordSet.ts

@@ -12,15 +12,15 @@ import {StoreRecord, StoreRecordId} from '../StoreRecord';
 import {Store} from '../Store';
 import {Filter} from '../filter/Filter';
 
+type StoreRecordMap = Map<StoreRecordId, StoreRecord>;
+type ChildRecordMap = Map<StoreRecordId, StoreRecord[]>;
+
 /**
  * Internal container for StoreRecord management within a Store.
  * Note this is an immutable object; its update and filtering APIs return new instances as required.
  *
  * @internal
  */
-type StoreRecordMap = Map<StoreRecordId, StoreRecord>;
-type ChildRecordMap = Map<StoreRecordId, StoreRecord[]>;
-
 export class RecordSet {
     store: Store;
     recordMap: StoreRecordMap; // Map of all Records by id

package/desktop/cmp/input/DateInput.ts

@@ -146,7 +146,7 @@ export interface DateInputProps extends HoistProps, LayoutProps, HoistInputProps
     /**
      * Type of value to publish. Defaults to 'date'. The use of 'localDate' is often a good
      * choice for use cases where there is no time component.
-     * @see LocalDate - the class that will be published when localDate mode.
+     * @see LocalDate
      */
     valueType?: 'date' | 'localDate';
 }

package/desktop/cmp/leftrightchooser/LeftRightChooserModel.ts

@@ -100,7 +100,7 @@ export class LeftRightChooserModel extends HoistModel {
      * Note that this will *not* affect the actual 'value' property, which will continue
      * to include unfiltered records.
      *
-     * @see LeftRightChooserFilter - a component to easily control this field.
+     * @see LeftRightChooserFilter
      * @param fn - predicate function for filtering.
      */
     setDisplayFilter(fn: FilterTestFn) {

package/mcp/cli/ts.ts

@@ -6,7 +6,13 @@
  */
 import {Command} from 'commander';
 
-import {searchSymbols, searchMembers, getSymbolDetail, getMembers} from '../data/ts-registry.js';
+import {
+    searchSymbols,
+    searchMembers,
+    getSymbolDetail,
+    getMembers,
+    getCompanionSymbols
+} from '../data/ts-registry.js';
 import {formatSymbolSearch, formatSymbolDetail, formatMembers} from '../formatters/typescript.js';
 
 const VALID_KINDS = ['class', 'interface', 'type', 'function', 'const', 'enum'] as const;
@@ -101,7 +107,8 @@ program
             process.exit(1);
         }
 
-        let text = formatSymbolDetail(detail, name);
+        const companions = await getCompanionSymbols(detail);
+        let text = formatSymbolDetail(detail, name, companions);
         if (detail.kind === 'class' || detail.kind === 'interface') {
             text +=
                 '\n\nTip: Use `hoist-ts members ' + name + '` to see all properties and methods.';

package/mcp/data/ts-registry.ts

@@ -15,7 +15,7 @@
  * Detailed symbol info is extracted on-demand.
  */
 import {Project, Node, Scope, SyntaxKind} from 'ts-morph';
-import type {ClassDeclaration, SourceFile} from 'ts-morph';
+import type {ClassDeclaration, FunctionDeclaration, SourceFile} from 'ts-morph';
 import {resolve} from 'node:path';
 
 import {log} from '../util/logger.js';
@@ -35,6 +35,8 @@ export interface SymbolEntry {
     filePath: string;
     isExported: boolean;
     sourcePackage: string;
+    /** JSDoc, if available. Populated at index time; displayed in search results. */
+    jsDoc: string;
 }
 
 /** Detailed symbol information extracted on-demand. */
@@ -285,7 +287,8 @@ function buildSymbolIndex(proj: Project): {
                 kind: 'class',
                 filePath,
                 isExported: cls.isExported(),
-                sourcePackage: pkg
+                sourcePackage: pkg,
+                jsDoc: extractJsDoc(cls)
             };
             addToIndex(index, entry);
             counts.total++;
@@ -308,7 +311,7 @@ function buildSymbolIndex(proj: Project): {
                             sourcePackage: pkg,
                             isStatic: m.isStatic,
                             type: m.kind === 'method' ? formatMethodType(m) : m.type,
-                            jsDoc: m.jsDoc.split('\n')[0],
+                            jsDoc: m.jsDoc,
                             decorators: m.decorators
                         };
                         addToMemberIndex(mIndex, mEntry);
@@ -324,12 +327,15 @@ function buildSymbolIndex(proj: Project): {
         for (const iface of sourceFile.getInterfaces()) {
             const name = iface.getName();
             if (!name) continue;
+            let jsDoc = extractJsDoc(iface);
+            if (!jsDoc) jsDoc = extractCompanionJsDoc(sourceFile, name);
             const entry: SymbolEntry = {
                 name,
                 kind: 'interface',
                 filePath,
                 isExported: iface.isExported(),
-                sourcePackage: pkg
+                sourcePackage: pkg,
+                jsDoc
             };
             addToIndex(index, entry);
             counts.total++;
@@ -346,7 +352,8 @@ function buildSymbolIndex(proj: Project): {
                 kind: 'type',
                 filePath,
                 isExported: typeAlias.isExported(),
-                sourcePackage: pkg
+                sourcePackage: pkg,
+                jsDoc: extractJsDoc(typeAlias)
             };
             addToIndex(index, entry);
             counts.total++;
@@ -363,7 +370,8 @@ function buildSymbolIndex(proj: Project): {
                 kind: 'function',
                 filePath,
                 isExported: func.isExported(),
-                sourcePackage: pkg
+                sourcePackage: pkg,
+                jsDoc: extractFunctionJsDoc(func)
             };
             addToIndex(index, entry);
             counts.total++;
@@ -380,7 +388,8 @@ function buildSymbolIndex(proj: Project): {
                 kind: 'enum',
                 filePath,
                 isExported: enumDecl.isExported(),
-                sourcePackage: pkg
+                sourcePackage: pkg,
+                jsDoc: extractJsDoc(enumDecl)
             };
             addToIndex(index, entry);
             counts.total++;
@@ -391,6 +400,7 @@ function buildSymbolIndex(proj: Project): {
         // Exported const variables
         for (const stmt of sourceFile.getVariableStatements()) {
             if (!stmt.isExported()) continue;
+            const stmtJsDoc = extractJsDoc(stmt);
             for (const decl of stmt.getDeclarations()) {
                 // For destructured exports (e.g. `export const [Foo, foo] = ...`),
                 // index each binding element as a separate symbol so both the
@@ -420,7 +430,8 @@ function buildSymbolIndex(proj: Project): {
                         kind: 'const',
                         filePath,
                         isExported: true,
-                        sourcePackage: pkg
+                        sourcePackage: pkg,
+                        jsDoc: stmtJsDoc
                     };
                     addToIndex(index, entry);
                     counts.total++;
@@ -508,7 +519,7 @@ function indexPromiseExtensions(
                     sourcePackage: pkg,
                     isStatic: false,
                     type: `(${paramStr}) => ${returnType}`,
-                    jsDoc: jsDoc.split('\n')[0],
+                    jsDoc,
                     decorators: []
                 });
 
@@ -518,7 +529,8 @@ function indexPromiseExtensions(
                     kind: 'function',
                     filePath,
                     isExported: true,
-                    sourcePackage: pkg
+                    sourcePackage: pkg,
+                    jsDoc
                 });
 
                 // Pre-compute detail for `getSymbolDetail()` since these can't be
@@ -703,6 +715,55 @@ export async function getSymbolDetail(
     }
 }
 
+/**
+ * Find companion symbols for cross-referencing in detail output.
+ *
+ * For a Props interface (e.g. `PanelProps`), returns the companion component
+ * consts (`Panel`, `panel`) from the same file. For a component const, returns
+ * the companion Props interface. Returns an empty array if no companions found.
+ */
+export async function getCompanionSymbols(entry: SymbolEntry): Promise<SymbolEntry[]> {
+    await ensureInitialized();
+
+    if (entry.kind === 'interface' && entry.name.endsWith('Props')) {
+        // Props interface → look for companion component consts
+        const baseName = entry.name.slice(0, -5);
+        if (!baseName) return [];
+        return findCompanionEntries(baseName, entry.filePath);
+    }
+
+    if (entry.kind === 'const') {
+        // Component const → look for companion Props interface
+        const pascalName = entry.name[0].toUpperCase() + entry.name.slice(1) + 'Props';
+        const key = pascalName.toLowerCase();
+        const entries = symbolIndex!.get(key);
+        if (!entries) return [];
+        return entries.filter(
+            e => e.name === pascalName && e.kind === 'interface' && e.filePath === entry.filePath
+        );
+    }
+
+    return [];
+}
+
+/** Find companion const entries (PascalCase and camelCase) in the same file. */
+function findCompanionEntries(baseName: string, filePath: string): SymbolEntry[] {
+    const results: SymbolEntry[] = [];
+    const camelName = baseName[0].toLowerCase() + baseName.slice(1);
+
+    for (const name of [baseName, camelName]) {
+        const key = name.toLowerCase();
+        const entries = symbolIndex!.get(key);
+        if (!entries) continue;
+        for (const e of entries) {
+            if (e.name === name && e.kind === 'const' && e.filePath === filePath) {
+                results.push(e);
+            }
+        }
+    }
+    return results;
+}
+
 /**
  * Get members (properties, methods, accessors) of a class or interface.
  *
@@ -929,6 +990,45 @@ function extractJsDoc(node: {getJsDocs?: () => Array<{getDescription: () => stri
     }
 }
 
+/**
+ * For a Props interface (e.g. `PanelProps`), look up the companion component's
+ * JSDoc from the same file. Uses the reliable `FooProps → Foo/foo` naming
+ * convention: strips the `Props` suffix and checks for a matching exported const.
+ *
+ * Returns the companion JSDoc string, or empty string if no match is found.
+ */
+function extractCompanionJsDoc(sourceFile: SourceFile, propsName: string): string {
+    if (!propsName.endsWith('Props')) return '';
+    const companionName = propsName.slice(0, -5);
+    if (!companionName) return '';
+
+    // Look for `const [Foo, foo] = ...` or `const foo = ...` in the same file
+    const varDecl =
+        sourceFile.getVariableDeclaration(companionName) ??
+        sourceFile.getVariableDeclaration(companionName[0].toLowerCase() + companionName.slice(1));
+    if (!varDecl) return '';
+
+    const varStmt = varDecl.getFirstAncestorByKind(SyntaxKind.VariableStatement);
+    return varStmt ? extractJsDoc(varStmt) : '';
+}
+
+/**
+ * Extract JSDoc from a function, falling back to the first overload signature if the
+ * implementation has no JSDoc. TypeScript best practice places JSDoc on overload signatures
+ * (which are visible to consumers) rather than the implementation (which is hidden).
+ */
+function extractFunctionJsDoc(func: FunctionDeclaration): string {
+    const implDoc = extractJsDoc(func);
+    if (implDoc) return implDoc;
+
+    const overloads = func.getOverloads();
+    for (const overload of overloads) {
+        const doc = extractJsDoc(overload);
+        if (doc) return doc;
+    }
+    return '';
+}
+
 /** Safely extract a type's text representation. */
 function safeGetTypeText(node: Node, enclosing?: Node): string {
     try {
@@ -996,10 +1096,14 @@ function extractInterfaceDetail(
     const braceIdx = text.indexOf('{');
     const signature = braceIdx === -1 ? text.trim() : text.slice(0, braceIdx).trim();
 
+    // For Props interfaces without their own JSDoc, inherit from the companion component
+    let jsDoc = extractJsDoc(iface);
+    if (!jsDoc) jsDoc = extractCompanionJsDoc(sourceFile, name);
+
     return {
         ...base,
         signature,
-        jsDoc: extractJsDoc(iface),
+        jsDoc,
         ...(extendsClauses.length > 0 ? {extends: extendsClauses.join(', ')} : {})
     };
 }
@@ -1056,7 +1160,7 @@ function extractFunctionDetail(
     return {
         ...base,
         signature,
-        jsDoc: extractJsDoc(func)
+        jsDoc: extractFunctionJsDoc(func)
     };
 }
 

package/mcp/formatters/typescript.ts

@@ -7,6 +7,14 @@
 import type {MemberInfo, MemberIndexEntry, SymbolEntry, SymbolDetail} from '../data/ts-registry.js';
 import {resolveRepoRoot} from '../util/paths.js';
 
+/** Remove blank lines from a JSDoc string to produce more compact output. */
+function collapseJsDoc(jsDoc: string): string {
+    return jsDoc
+        .split('\n')
+        .filter(l => l.trim().length > 0)
+        .join('\n');
+}
+
 /** Maximum length for type strings before truncation. */
 const MAX_TYPE_LENGTH = 200;
 
@@ -45,7 +53,11 @@ export function formatMember(member: MemberInfo): string {
     }
 
     if (member.jsDoc) {
-        lines.push(`    ${member.jsDoc.split('\n')[0]}`);
+        const indented = collapseJsDoc(member.jsDoc)
+            .split('\n')
+            .map(l => `    ${l}`)
+            .join('\n');
+        lines.push(indented);
     }
 
     return lines.join('\n');
@@ -62,7 +74,11 @@ export function formatMemberIndexEntry(entry: MemberIndexEntry, index: number):
         `${index}. [${entry.memberKind}] ${staticPrefix}${entry.name}: ${typeStr} (on ${entry.ownerName} \u2014 ${entry.ownerDescription})`
     );
     if (entry.jsDoc) {
-        lines.push(`    ${entry.jsDoc}`);
+        const indented = collapseJsDoc(entry.jsDoc)
+            .split('\n')
+            .map(l => `    ${l}`)
+            .join('\n');
+        lines.push(indented);
     }
     return lines.join('\n');
 }
@@ -81,6 +97,13 @@ export function formatSymbolSearch(
             lines.push(
                 `${i + 1}. [${result.kind}] ${result.name} (package: ${result.sourcePackage}, file: ${toRelativePath(result.filePath)}, exported: ${result.isExported ? 'yes' : 'no'})`
             );
+            if (result.jsDoc) {
+                const indented = collapseJsDoc(result.jsDoc)
+                    .split('\n')
+                    .map(l => `    ${l}`)
+                    .join('\n');
+                lines.push(indented);
+            }
         });
     }
 
@@ -100,7 +123,11 @@ export function formatSymbolSearch(
 }
 
 /** Format detailed symbol information as a readable text block. */
-export function formatSymbolDetail(detail: SymbolDetail | null, name: string): string {
+export function formatSymbolDetail(
+    detail: SymbolDetail | null,
+    name: string,
+    companionSymbols?: SymbolEntry[]
+): string {
     if (!detail) {
         return `Symbol '${name}' not found. Use search to find available symbols.`;
     }
@@ -132,7 +159,26 @@ export function formatSymbolDetail(detail: SymbolDetail | null, name: string): s
     if (detail.jsDoc) {
         lines.push('');
         lines.push('## Documentation');
-        lines.push(detail.jsDoc);
+        lines.push(collapseJsDoc(detail.jsDoc));
+    }
+
+    // Cross-reference: link Props interfaces to their companion component and vice versa
+    if (companionSymbols && companionSymbols.length > 0) {
+        lines.push('');
+        const companionNames = companionSymbols.map(s => `\`${s.name}\``).join(', ');
+        if (detail.kind === 'interface' && detail.name.endsWith('Props')) {
+            lines.push(`## Component`);
+            lines.push(
+                `This is the Props interface for ${companionNames}. ` +
+                    `Use hoist-get-members on ${detail.name} to see all available props.`
+            );
+        } else {
+            const propsName = companionSymbols[0].name;
+            lines.push(`## Props`);
+            lines.push(
+                `Accepts \`${propsName}\` — use hoist-get-members on ${propsName} to see all available props.`
+            );
+        }
     }
 
     return lines.join('\n');

package/mcp/tools/typescript.ts

@@ -8,7 +8,13 @@
 import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
 import {z} from 'zod';
 
-import {searchSymbols, searchMembers, getSymbolDetail, getMembers} from '../data/ts-registry.js';
+import {
+    searchSymbols,
+    searchMembers,
+    getSymbolDetail,
+    getMembers,
+    getCompanionSymbols
+} from '../data/ts-registry.js';
 import {formatSymbolSearch, formatSymbolDetail, formatMembers} from '../formatters/typescript.js';
 
 /**
@@ -100,7 +106,8 @@ export function registerTsTools(server: McpServer): void {
         },
         async ({name, filePath}) => {
             const detail = await getSymbolDetail(name, filePath);
-            let text = formatSymbolDetail(detail, name);
+            const companions = detail ? await getCompanionSymbols(detail) : [];
+            let text = formatSymbolDetail(detail, name, companions);
 
             if (detail && (detail.kind === 'class' || detail.kind === 'interface')) {
                 text += '\n\nUse hoist-get-members to see all properties and methods.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "83.0.1",
+  "version": "83.1.0",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": {
     "type": "git",
@@ -108,7 +108,7 @@
   "devDependencies": {
     "@types/react": "18.x",
     "@types/react-dom": "18.x",
-    "@xh/hoist-dev-utils": "11.x",
+    "@xh/hoist-dev-utils": "12.x",
     "ag-grid-community": "34.x",
     "ag-grid-react": "34.x",
     "csstype": "3.x",

package/svc/AutoRefreshService.ts

@@ -24,7 +24,7 @@ import {withDefault} from '@xh/hoist/utils/js';
  *     to customize via the global options dialog, or set a default pref value if per-user
  *     customization is not desirable.
  *
- * @see RefreshContextModel - the underlying mechanism used to implement the refresh.
+ * @see RefreshContextModel
  */
 export class AutoRefreshService extends HoistService {
     override xhImpl = true;

package/svc/ChangelogService.ts

@@ -26,9 +26,8 @@ import {isEmpty, forOwn, includes} from 'lodash';
  *
  * Several additional options can be controlled via soft-config - see below.
  *
- * @see XH.showChangelog - public API for displaying the changelog, if enabled and populated.
- * @see whatsNewButton - utility button that conditionally renders when an unread entry exists for
- *      the currently deployed app version. Installed by default in desktop appBar.
+ * @see XH.showChangelog
+ * @see whatsNewButton
  */
 export class ChangelogService extends HoistService {
     override xhImpl = true;

package/svc/EnvironmentService.ts

@@ -162,16 +162,18 @@ export class EnvironmentService extends HoistService {
 
     private ensureVersionRunnable() {
         const hcVersion = this.get('hoistCoreVersion'),
-            clientVersion = this.get('appVersion'),
-            serverVersion = this.serverVersion;
+            // This app version value is sourced by the network call to 'xh/environment'.
+            serverAppVersion = this.get('appVersion'),
+            // This app version value is packaged from configureWebpack -> appVersion.
+            clientAppVersion = this.get('clientVersion');
 
         // Check for client/server mismatch version.  It's an ok transitory state *during* the
         // client app lifetime, but app should *never* start this way, would indicate caching issue.
         throwIf(
-            clientVersion != serverVersion,
+            clientAppVersion != serverAppVersion,
             XH.exception(
-                `The version of this client (${clientVersion}) is out of sync with the
-                available server (${serverVersion}). Please reload to continue.`
+                `The version of this client (${clientAppVersion}) is out of sync with the
+                available server (${serverAppVersion}). Please reload to continue.`
             )
         );