@xh/hoist 86.0.0 → 86.1.0

package/svc/TraceService.ts

@@ -4,10 +4,11 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {HoistService, InitContext, PlainObject, XH, Span, FullSpanConfig} from '@xh/hoist/core';
+import {HoistService, PlainObject, XH, Span, FullSpanConfig} from '@xh/hoist/core';
 import {SECONDS} from '@xh/hoist/utils/datetime';
 import {debounced, parseNameSource} from '@xh/hoist/utils/js';
-import {every, forEach, groupBy, isEmpty, isString, omitBy} from 'lodash';
+import {every, forEach, groupBy, isEmpty, isString, omitBy, takeRight} from 'lodash';
+import {terminationSafePostJson} from './impl/Fetch';
 
 /**
  * Client-side distributed tracing service for Hoist applications.
@@ -48,8 +49,14 @@ export class TraceService extends HoistService {
     //------------------
     // Initialization
     //------------------
-    override async initAsync(ctx: InitContext) {
-        window.addEventListener('beforeunload', () => this.pushPendingAsync());
+    override async initAsync() {
+        // Flush on page teardown while the page is still alive.
+        this.addReaction({
+            track: () => XH.pageState,
+            run: () => {
+                if (!XH.pageIsVisible) this.pushPendingInternalAsync();
+            }
+        });
     }
 
     //------------------
@@ -159,44 +166,11 @@ export class TraceService extends HoistService {
     }
 
     /**
-     * Push all pending spans to the server.
-     * Called on debounced interval and on page unload.
+     * Flush the queue of pending spans to the server.
+     * @internal - apps should generally allow this service to manage w/its internal debounce.
      */
     async pushPendingAsync() {
-        const spans = this._pending;
-        if (isEmpty(spans)) return;
-
-        this._pending = [];
-        try {
-            await XH.postJson({
-                url: 'xh/submitSpans',
-                body: spans.map(s => s.toJSON()),
-                params: {
-                    clientUsername: XH.getUsername()
-                }
-            });
-        } catch (e) {
-            if (isRetryableError(e)) {
-                // Transient failure - re-queue the batch (ahead of newer spans) to retry on the
-                // next flush, then bound the buffer in case the outage is prolonged.
-                this._pending = [...spans, ...this._pending];
-                this.enforceCap();
-                this.logError('Failed to push spans - will retry on next flush', e);
-            } else {
-                // Permanent (client-side) rejection - drop the batch so it can't deadlock the
-                // pipe (e.g. a session mismatch or oversized payload would fail forever).
-                this.logError('Server rejected span batch - dropping', e);
-            }
-        }
-    }
-
-    /** Bound the pending buffer, silently dropping oldest spans (failed pushes are logged). */
-    private enforceCap() {
-        const {_pending} = this,
-            {MAX_PENDING} = TraceService;
-        if (_pending.length > MAX_PENDING) {
-            _pending.splice(0, _pending.length - MAX_PENDING);
-        }
+        return this.pushPendingInternalAsync();
     }
 
     /**
@@ -237,7 +211,45 @@ export class TraceService extends HoistService {
 
     @debounced(5 * SECONDS)
     private pushPendingBuffered() {
-        void this.pushPendingAsync();
+        void this.pushPendingInternalAsync();
+    }
+
+    /** Flush all pending spans to the server. */
+    private async pushPendingInternalAsync() {
+        const spans = this._pending;
+        if (isEmpty(spans)) return;
+
+        // Clear synchronously with the capture, so overlapping flushes cannot post twice.
+        this._pending = [];
+        try {
+            await terminationSafePostJson({
+                url: 'xh/submitSpans',
+                body: spans.map(s => s.toJSON()),
+                params: {
+                    clientUsername: XH.getUsername()
+                }
+            });
+        } catch (e) {
+            if (isRetryableError(e)) {
+                // Transient failure - re-queue the batch (ahead of newer spans) to retry on the
+                // next flush, then bound the buffer in case the outage is prolonged.
+                this._pending = [...spans, ...this._pending];
+                this.enforceCap();
+                this.logError('Failed to push spans - will retry on next flush', e);
+            } else {
+                // Permanent (client-side) rejection - drop the batch so it can't deadlock the
+                // pipe (e.g. a session mismatch or oversized payload would fail forever).
+                this.logError('Server rejected span batch - dropping', e);
+            }
+        }
+    }
+
+    /** Bound the pending buffer, silently dropping oldest spans (failed pushes are logged). */
+    private enforceCap() {
+        const {MAX_PENDING} = TraceService;
+        if (this._pending.length > MAX_PENDING) {
+            this._pending = takeRight(this._pending, MAX_PENDING);
+        }
     }
 
     /**

package/svc/TrackService.ts

@@ -4,11 +4,12 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {HoistService, InitContext, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
+import {HoistService, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
 import {SECONDS} from '@xh/hoist/utils/datetime';
 import {isOmitted} from '@xh/hoist/utils/impl';
 import {debounced, stripTags, withDefault} from '@xh/hoist/utils/js';
 import {isEmpty, isNil, isString} from 'lodash';
+import {terminationSafePostJson} from './impl/Fetch';
 
 /**
  * Primary service for tracking any activity that an application's admins want to track.
@@ -23,8 +24,14 @@ export class TrackService extends HoistService {
     private oncePerSessionSent = new Map();
     private pending: PlainObject[] = [];
 
-    override async initAsync(ctx: InitContext) {
-        window.addEventListener('beforeunload', () => this.pushPendingAsync());
+    override async initAsync() {
+        // Flush on page teardown while the page is still alive
+        this.addReaction({
+            track: () => XH.pageState,
+            run: () => {
+                if (!XH.pageIsVisible) this.pushPendingAsync();
+            }
+        });
     }
 
     get conf(): ActivityTrackingConfig {
@@ -94,25 +101,29 @@ export class TrackService extends HoistService {
 
     /**
      * Flush the queue of pending activity tracking messages to the server.
-     * @internal - apps should generally allow this service to manage w/its internal debounce.
+     *
+     * Not typically called by applications.  Called automatically by the framework via a
+     * debounce and when the page is hidden/terminated.
      */
     async pushPendingAsync() {
         const {pending} = this;
         if (isEmpty(pending)) return;
 
+        // Clear synchronously with the capture, so overlapping flushes cannot post twice.
+        this.pending = [];
+
         await this.runner()
             .span('push')
-            .run(async ctx => {
-                this.pending = [];
-                await XH.postJson(
+            .run(ctx =>
+                terminationSafePostJson(
                     {
                         url: 'xh/track',
                         body: {entries: pending},
                         params: {clientUsername: XH.getUsername()}
                     },
                     ctx
-                );
-            });
+                )
+            );
     }
 
     //------------------
@@ -120,7 +131,7 @@ export class TrackService extends HoistService {
     //------------------
     @debounced(10 * SECONDS)
     private pushPendingBuffered() {
-        this.pushPendingAsync();
+        void this.pushPendingAsync();
     }
 
     private toServerJson(options: TrackOptions): PlainObject {

package/svc/impl/Fetch.ts

@@ -0,0 +1,33 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2026 Extremely Heavy Industries Inc.
+ */
+import {CallContextLike, XH} from '@xh/hoist/core';
+import type {FetchOptions} from '../FetchService';
+
+/**
+ * Post a JSON body, using `fetch({keepalive: true})` when the page is no longer visible so the
+ * request can survive teardown (e.g. a flush as `XH.pageState` goes `hidden`/`frozen`/`terminated`).
+ *
+ * Keepalive bodies share a single browser-wide 64KB budget; if exceeded the request is never sent
+ * and we retry once uncapped (without keepalive), which still completes while the page is alive (the
+ * common `hidden` case). Real server errors are re-thrown, not re-posted.
+ *
+ * @internal
+ */
+export async function terminationSafePostJson(
+    opts: FetchOptions,
+    ctx?: CallContextLike
+): Promise<any> {
+    if (XH.pageIsVisible) return XH.postJson(opts, ctx);
+
+    try {
+        return await XH.postJson({...opts, fetchOpts: {...opts.fetchOpts, keepalive: true}}, ctx);
+    } catch (e: any) {
+        // Retry uncapped if keepalive was never sent (over-budget); re-throw real server errors.
+        if (e.isServerUnavailable) return XH.postJson(opts, ctx);
+        throw e;
+    }
+}

package/utils/js/ClipboardUtils.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {XH} from '@xh/hoist/core';
+import {Exception} from '@xh/hoist/exception';
 
 /**
  * Copy the given text to the system clipboard.
@@ -53,5 +53,5 @@ function copyViaExecCommand(text: string): void {
         selection.removeAllRanges();
         document.body.removeChild(span);
     }
-    if (!success) throw XH.exception('Clipboard copy not allowed');
+    if (!success) throw Exception.create('Clipboard copy not allowed');
 }

package/utils/js/TestUtils.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {HoistProps} from '@xh/hoist/core';
+import type {HoistProps} from '@xh/hoist/core';
 import {isString} from 'lodash';
 
 /**

package/utils/react/LayoutPropUtils.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {LayoutProps, ResolvedLayoutProps, PlainObject} from '@xh/hoist/core';
+import type {LayoutProps, ResolvedLayoutProps, PlainObject} from '@xh/hoist/core';
 import {forOwn, isEmpty, isNumber, isString, isNil, omit, pick} from 'lodash';
 
 const XH_PAD_VAR = 'var(--xh-pad-px)';

package/utils/react/ReactUtils.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {Content} from '@xh/hoist/core';
+import type {Content} from '@xh/hoist/core';
 import {ReactElement, cloneElement, createElement, isValidElement} from 'react';
 import {isFunction, isNil} from 'lodash';
 import {renderToStaticMarkup as reactRenderToStaticMarkup} from 'react-dom/server';