@elizaos/ui 2.0.3-beta.2 → 2.0.3-beta.4

package/first-run/use-first-run-controller.js

@@ -11,10 +11,10 @@ import * as React from "react";
 import { client } from "../api/index.js";
 import { getCloudAuthToken, isDirectCloudSharedAgentBase, } from "../api/client-cloud.js";
 import { getDesktopRuntimeMode, invokeDesktopBridgeRequest } from "../bridge/index.js";
+import { runCloudAgentHandoff } from "../cloud/handoff/run-cloud-agent-handoff.js";
 import { getBootConfig } from "../config/boot-config.js";
-import { dispatchCloudHandoffPhase } from "../events/index.js";
 import { canSelectLocalRuntime, isAndroid, isDesktopPlatform, isIOS, } from "../platform/init.js";
-import { addAgentProfile, createPersistedActiveServer, loadPersistedActiveServer, savePersistedActiveServer, useApp, } from "../state/index.js";
+import { addAgentProfile, createPersistedActiveServer, loadPersistedActiveServer, savePersistedActiveServer, useAppSelectorShallow, } from "../state/index.js";
 import { isCloudStatusAuthenticated, preOpenWindow } from "../utils/index.js";
 import { createVoiceCapture, } from "../voice/index.js";
 import { isLocalAsrCaptureSupported } from "../voice/local-asr-capture.js";
@@ -196,7 +196,19 @@ function normalizeRemoteTarget(value) {
     return parsed.toString().replace(/\/+$/, "");
 }
 export function useFirstRunController() {
-    const { completeFirstRun, elizaCloudConnected, elizaCloudLoginBusy, elizaCloudLoginError, handleCloudLogin, firstRunName, showActionBanner, setTab, setState, switchAgentProfile, uiLanguage, } = useApp();
+    const { completeFirstRun, elizaCloudConnected, elizaCloudLoginBusy, elizaCloudLoginError, handleCloudLogin, firstRunName, showActionBanner, setTab, setState, switchAgentProfile, uiLanguage, } = useAppSelectorShallow((s) => ({
+        completeFirstRun: s.completeFirstRun,
+        elizaCloudConnected: s.elizaCloudConnected,
+        elizaCloudLoginBusy: s.elizaCloudLoginBusy,
+        elizaCloudLoginError: s.elizaCloudLoginError,
+        handleCloudLogin: s.handleCloudLogin,
+        firstRunName: s.firstRunName,
+        showActionBanner: s.showActionBanner,
+        setTab: s.setTab,
+        setState: s.setState,
+        switchAgentProfile: s.switchAgentProfile,
+        uiLanguage: s.uiLanguage,
+    }));
     const initialRuntimeTarget = React.useMemo(readFirstRunRuntimeTarget, []);
     // Desktop cloud-only opt-in: branding.cloudOnly is set from the injected
     // __ELIZA_DESKTOP_RUNTIME_MODE__ signal (api-base-owner → main.tsx branding).
@@ -611,69 +623,40 @@ export function useFirstRunController() {
         // the shared adapter into it and switch the live client over — no waiting,
         // no lost history. Best-effort: on failure the user stays on the shared
         // adapter, which keeps working.
-        if (selectedAgent.created && !selectedAgent.bridgeUrl) {
+        if (selectedAgent.created &&
+            isDirectCloudSharedAgentBase(cloudAgentApiBase)) {
             const handoffAgentId = selectedAgent.agentId;
-            // Hoisted so the terminal `timed-out` / `failed` phases can hand the UI
-            // an `onRetry` closure that re-runs the IDENTICAL handoff.
-            const runHandoff = () => {
-                // Tell the UI a migration is in flight instead of swapping silently.
-                dispatchCloudHandoffPhase({
-                    agentId: handoffAgentId,
-                    phase: "migrating",
-                });
-                void client
-                    .startCloudAgentHandoff({
-                    agentId: handoffAgentId,
-                    sharedApiBase: cloudAgentApiBase,
-                    // The shared adapter keeps one canonical conversation per agent id.
-                    conversationId: handoffAgentId,
-                    cloudApiBase: getBootConfig().cloudApiBase || "https://www.elizacloud.ai",
-                    authToken,
-                    onSwitch: (containerBase) => {
-                        client.setBaseUrl(containerBase);
-                        client.setToken(authToken);
-                        const switched = createPersistedActiveServer({
-                            kind: "cloud",
-                            id: `cloud:${handoffAgentId}`,
-                            apiBase: containerBase,
-                            accessToken: authToken,
-                        });
-                        savePersistedActiveServer(switched);
-                        const profile = addAgentProfile({
-                            kind: "cloud",
-                            label: switched.label,
-                            apiBase: containerBase,
-                            accessToken: authToken,
-                        });
-                        switchAgentProfile(profile.id);
-                    },
-                })
-                    // Stop discarding the ConversationHandoffResult: surface each terminal
-                    // status (switched | switched-empty | timed-out | failed) as a typed
-                    // handoff phase so the UI can render real progress and an honest
-                    // failure notice. On a recoverable terminal phase (timed-out/failed)
-                    // attach an onRetry that re-runs this same handoff. Still best-effort —
-                    // the shared adapter keeps working regardless of outcome.
-                    .then((result) => {
-                    const recoverable = result.status === "timed-out" || result.status === "failed";
-                    dispatchCloudHandoffPhase({
-                        agentId: handoffAgentId,
-                        phase: result.status,
-                        imported: result.imported,
-                        ...(result.error ? { error: result.error } : {}),
-                        ...(recoverable ? { onRetry: runHandoff } : {}),
+            // Surface the handoff lifecycle (migrating → switched | timed-out |
+            // failed) as typed phase events instead of swapping silently, and keep
+            // a `timed-out`/`failed` retryable rather than a silent permanent
+            // fallback. The supervisor's import is idempotent, so a retry just
+            // re-runs the same call.
+            runCloudAgentHandoff(handoffAgentId, () => client.startCloudAgentHandoff({
+                agentId: handoffAgentId,
+                sharedApiBase: cloudAgentApiBase,
+                // The shared adapter keeps one canonical conversation per agent id.
+                conversationId: handoffAgentId,
+                cloudApiBase: getBootConfig().cloudApiBase || "https://www.elizacloud.ai",
+                authToken,
+                onSwitch: (containerBase) => {
+                    client.setBaseUrl(containerBase);
+                    client.setToken(authToken);
+                    const switched = createPersistedActiveServer({
+                        kind: "cloud",
+                        id: `cloud:${handoffAgentId}`,
+                        apiBase: containerBase,
+                        accessToken: authToken,
                     });
-                })
-                    .catch((err) => {
-                    dispatchCloudHandoffPhase({
-                        agentId: handoffAgentId,
-                        phase: "failed",
-                        error: err instanceof Error ? err.message : String(err),
-                        onRetry: runHandoff,
+                    savePersistedActiveServer(switched);
+                    const profile = addAgentProfile({
+                        kind: "cloud",
+                        label: switched.label,
+                        apiBase: containerBase,
+                        accessToken: authToken,
                     });
-                });
-            };
-            runHandoff();
+                    switchAgentProfile(profile.id);
+                },
+            }));
         }
     }, [completeFirstRun, switchAgentProfile, uiLanguage]);
     const finishCloud = React.useCallback(async (sourceDraft) => {
@@ -735,12 +718,25 @@ export function useFirstRunController() {
             setPickerError(list.error ?? "Could not load your agents. Try again.");
             return;
         }
+        // Auto-connect without the picker for the brand-new, 0-agent user, routing
+        // any failure (402/5xx/network) to the picker's error phase — which has
+        // Back + Try again — instead of stranding it on a permanent "Finding your
+        // agents…" spinner. Mirrors the onPickAgent failure handling.
+        const autoConnect = async (opts) => {
+            try {
+                await finishCloudWithSelection(sourceDraft, authToken, opts);
+            }
+            catch (err) {
+                setBusyText(null);
+                setPickerPhase("error");
+                setPickerError(err instanceof Error
+                    ? err.message
+                    : "Couldn't set up your agent. Try again.");
+            }
+        };
         if (list.data.length === 0) {
-            // Brand-new user: skip the picker and auto-create (current behavior, no
-            // extra click, no dead one-item-less UI).
-            await finishCloudWithSelection(sourceDraft, authToken, {
-                forceCreate: false,
-            });
+            // Brand-new user: skip the picker and auto-create (no extra click).
+            await autoConnect({ forceCreate: false });
             return;
         }
         // >=1 agents: render the picker (newest-first, running-prioritized to

package/genui/actions.d.ts

@@ -1,4 +1,4 @@
-import type { ElizaGenUiAction, ElizaGenUiActionContext, ElizaGenUiActionHandler, ElizaGenUiActionResult } from "./types";
+import type { ElizaGenUiAction, ElizaGenUiActionContext, ElizaGenUiActionHandler, ElizaGenUiActionResult } from "./types.js";
 export declare class ElizaGenUiActionError extends Error {
     readonly action: ElizaGenUiAction;
     constructor(message: string, action: ElizaGenUiAction);

package/genui/index.d.ts

@@ -1,9 +1,9 @@
-export * from "./actions";
-export * from "./catalog";
-export * from "./renderer";
-export * from "./starter-pack-demo";
-export * from "./streaming";
-export * from "./types";
-export * from "./use-ui-stream";
-export * from "./validator";
+export * from "./actions.js";
+export * from "./catalog.js";
+export * from "./renderer.js";
+export * from "./starter-pack-demo.js";
+export * from "./streaming.js";
+export * from "./types.js";
+export * from "./use-ui-stream.js";
+export * from "./validator.js";
 //# sourceMappingURL=index.d.ts.map

package/genui/modes.d.ts

@@ -1,4 +1,4 @@
-import type { ElizaGenUiMode, ElizaGenUiModeConfig } from "./types";
+import type { ElizaGenUiMode, ElizaGenUiModeConfig } from "./types.js";
 export declare const STANDALONE_MODE_PROMPT_RULES: string[];
 export declare const INLINE_MODE_PROMPT_RULES: string[];
 export declare function getModePromptRules(mode: ElizaGenUiMode, customRules?: readonly string[]): string;

package/genui/pipe.d.ts

@@ -1,5 +1,5 @@
 import { pipeJsonRender as officialPipeJsonRender } from "@json-render/core";
-import type { ElizaGenUiPatch, ElizaGenUiSpec, ElizaGenUiSpecStreamPart, ElizaGenUiValidationOptions } from "./types";
+import type { ElizaGenUiPatch, ElizaGenUiSpec, ElizaGenUiSpecStreamPart, ElizaGenUiValidationOptions } from "./types.js";
 export { officialPipeJsonRender as pipeJsonRender1 };
 export declare function pipeJsonRenderLines(input: string): ElizaGenUiSpecStreamPart[];
 export declare function pipeJsonRenderStream(chunks: AsyncIterable<string> | ReadableStream<string>, initialSpec?: ElizaGenUiSpec, validationOptions?: ElizaGenUiValidationOptions): ReadableStream<ElizaGenUiSpecStreamPart>;

package/genui/renderer.d.ts

@@ -1,4 +1,4 @@
 import * as React from "react";
-import type { ElizaGenUiRendererProps } from "./types";
+import type { ElizaGenUiRendererProps } from "./types.js";
 export declare function ElizaGenUiRenderer({ spec, actionHandlers, context, devMode, className, onActionError, }: ElizaGenUiRendererProps): React.ReactElement | null;
 //# sourceMappingURL=renderer.d.ts.map

package/genui/starter-pack-demo.d.ts

@@ -1,3 +1,3 @@
-import type { ElizaGenUiSpec } from "./types";
+import type { ElizaGenUiSpec } from "./types.js";
 export declare const ELIZA_STARTER_PACK_SETUP_SPEC: ElizaGenUiSpec;
 //# sourceMappingURL=starter-pack-demo.d.ts.map

package/genui/streaming.d.ts

@@ -1,4 +1,4 @@
-import type { ElizaGenUiPatch, ElizaGenUiPatchResult, ElizaGenUiSpec, ElizaGenUiValidationOptions } from "./types";
+import type { ElizaGenUiPatch, ElizaGenUiPatchResult, ElizaGenUiSpec, ElizaGenUiValidationOptions } from "./types.js";
 export declare function applyElizaGenUiPatch(spec: ElizaGenUiSpec, patches: readonly ElizaGenUiPatch[], options?: ElizaGenUiValidationOptions): ElizaGenUiPatchResult;
 export declare function resetElizaGenUiSpec(spec: ElizaGenUiSpec): ElizaGenUiSpec;
 export declare function abortElizaGenUiStream(reason: string): ElizaGenUiPatchResult;

package/genui/use-json-render-message.d.ts

@@ -1,5 +1,5 @@
 import { useJsonRenderMessage as officialUseJsonRenderMessage } from "@json-render/react";
-import type { ElizaGenUiSpec, ElizaGenUiValidationOptions } from "./types";
+import type { ElizaGenUiSpec, ElizaGenUiValidationOptions } from "./types.js";
 type MessagePart = {
     type: "text";
     text: string;

package/genui/use-ui-stream.d.ts

@@ -1,5 +1,5 @@
 import type { Spec as OfficialSpec } from "@json-render/core";
-import type { ElizaGenUiSendOptions, ElizaGenUiSpec, ElizaGenUiStreamOptions, ElizaGenUiStreamState } from "./types";
+import type { ElizaGenUiSendOptions, ElizaGenUiSpec, ElizaGenUiStreamOptions, ElizaGenUiStreamState } from "./types.js";
 export declare function officialSpecToEliza(spec: OfficialSpec | null): ElizaGenUiSpec | null;
 export declare function useUIStream(options: ElizaGenUiStreamOptions): ElizaGenUiStreamState & {
     send: (sendOptions?: ElizaGenUiSendOptions) => Promise<void>;

package/genui/use-ui-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-ui-stream.d.ts","sourceRoot":"","sources":["../../../../../src/genui/use-ui-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG9D,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,GAAG,IAAI,GACxB,cAAc,GAAG,IAAI,CAqBvB;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,uBAAuB,GAC/B,qBAAqB,GAAG;IACzB,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAyCA"}
+{"version":3,"file":"use-ui-stream.d.ts","sourceRoot":"","sources":["../../../../../src/genui/use-ui-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG9D,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,GAAG,IAAI,GACxB,cAAc,GAAG,IAAI,CAkBvB;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,uBAAuB,GAC/B,qBAAqB,GAAG;IACzB,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CA4CA"}

package/genui/use-ui-stream.js

@@ -5,10 +5,7 @@ export function officialSpecToEliza(spec) {
         return null;
     const { root, elements, state } = spec;
     const components = Object.entries(elements).map(([id, el]) => {
-        const record = el;
-        const type = record.type;
-        const props = record.props;
-        const children = record.children;
+        const { type, props, children } = el;
         return {
             id,
             component: type ?? "unknown",
@@ -30,7 +27,10 @@ export function useUIStream(options) {
         onError,
         onComplete: onComplete
             ? (spec) => {
-                onComplete(spec);
+                // Convert the json-render OfficialSpec (keyed `elements`) into the
+                // ElizaGenUiSpec (array `components`) consumers are typed against —
+                // the same conversion applied to the returned `spec` below.
+                onComplete(officialSpecToEliza(spec));
             }
             : undefined,
     });

package/genui/validator.d.ts

@@ -1,4 +1,4 @@
-import type { ElizaGenUiSpec, ElizaGenUiValidationOptions, ElizaGenUiValidationResult } from "./types";
+import type { ElizaGenUiSpec, ElizaGenUiValidationOptions, ElizaGenUiValidationResult } from "./types.js";
 export declare function validateElizaGenUiSpec(value: unknown, validationOptions?: ElizaGenUiValidationOptions): ElizaGenUiValidationResult;
 export declare function assertValidElizaGenUiSpec(value: unknown, options?: ElizaGenUiValidationOptions): ElizaGenUiSpec;
 //# sourceMappingURL=validator.d.ts.map

package/hooks/BugReportProvider.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import { type BugReportContextValue } from "./useBugReport.hooks";
+import { type BugReportContextValue } from "./useBugReport.hooks.js";
 export declare function BugReportProvider({ children, value, }: {
     children: ReactNode;
     value: BugReportContextValue;

package/hooks/frame-budget.d.ts

@@ -0,0 +1,124 @@
+/** A frame-rate target. 60 → a 16.67ms budget; 120 → 8.33ms (ProMotion). */
+export interface FrameBudget {
+    targetFps: number;
+}
+export declare const DEFAULT_FRAME_BUDGET: FrameBudget;
+/** The per-frame budget in milliseconds for a target frame rate. */
+export declare function frameBudgetMs(budget?: FrameBudget): number;
+export interface FrameBudgetSummary {
+    /** Number of frame-duration samples in the window. */
+    sampleCount: number;
+    /** Observed frame rate, derived from the mean frame duration. */
+    fps: number;
+    /** Mean frame duration (ms). */
+    meanFrameMs: number;
+    /** 95th-percentile frame duration (ms) — the number the budget is asserted on. */
+    p95FrameMs: number;
+    /** Slowest single frame in the window (ms). */
+    worstFrameMs: number;
+    /** Frames whose duration exceeded the budget (i.e. a dropped/janky frame). */
+    droppedFrames: number;
+    /** `PerformanceObserver('longtask')` entries observed in the window. */
+    longTasks: number;
+    /** The per-frame budget the summary was computed against (ms). */
+    budgetMs: number;
+}
+/**
+ * Nearest-rank percentile over an unsorted sample set. `p` is a fraction in
+ * (0, 1]; an empty set yields 0. Deterministic — no interpolation, so the same
+ * samples always yield the same number (stable for snapshot/KPI assertions).
+ */
+export declare function percentile(values: readonly number[], p: number): number;
+/**
+ * Reduce a window of frame durations into a budget summary. `frameDurationsMs`
+ * is the list of inter-frame deltas (ms); `longTasks` is the count of long-task
+ * entries seen in the same window.
+ */
+export declare function summarizeFrameSamples(frameDurationsMs: readonly number[], longTasks?: number, budget?: FrameBudget): FrameBudgetSummary;
+export interface FrameBudgetReportOptions {
+    /**
+     * Report when the p95 frame exceeds the budget by this factor. A little slack
+     * (default 1.25×) avoids flagging the occasional unavoidable frame while still
+     * catching sustained jank. Must be ≥ 1.
+     */
+    p95BudgetFactor?: number;
+    /** Report when at least this fraction of frames were dropped (default 0.1). */
+    droppedFrameRatio?: number;
+    /** Report when any long task is observed (default true). */
+    reportOnLongTask?: boolean;
+}
+/**
+ * Whether a window's summary is bad enough to surface (HUD highlight / telemetry
+ * event). Kept separate from the math so the threshold policy is testable and
+ * the HUD and a KPI spec can apply the same rule.
+ */
+export declare function shouldReportFrameBudget(summary: FrameBudgetSummary, options?: FrameBudgetReportOptions): boolean;
+/** Telemetry payload emitted on the shared RENDER_TELEMETRY_EVENT channel. */
+export interface FrameBudgetTelemetryEvent {
+    source: "frameBudget";
+    severity: "info" | "error";
+    summary: FrameBudgetSummary;
+    windowMs: number;
+    at: number;
+    sequence: number;
+    route?: string;
+}
+type RafLike = (cb: (now: number) => void) => number;
+type CancelRafLike = (handle: number) => void;
+export interface FrameBudgetSamplerOptions {
+    /** Max frame deltas retained in the rolling window. Default 120 (~1-2s). */
+    windowSize?: number;
+    /** Frame-rate target used by `summary()`. Default 60fps. */
+    budget?: FrameBudget;
+    /** Injectable rAF for tests; defaults to `requestAnimationFrame`. */
+    raf?: RafLike;
+    /** Injectable cancel for tests; defaults to `cancelAnimationFrame`. */
+    cancelRaf?: CancelRafLike;
+    /**
+     * Called on every sampled frame with the running sampler. The dev HUD polls
+     * `summary()` on an interval; the telemetry monitor uses this to flush + reset
+     * on a fixed time window. Kept optional so the sampler stays a pure collector.
+     */
+    onFrame?: (timestamp: number, sampler: FrameBudgetSampler) => void;
+    /**
+     * Observe `PerformanceObserver('longtask')` entries while running (default
+     * true). Long tasks block the main thread past a frame budget without ever
+     * showing up as a slow rAF delta, so they are a first-class budget signal.
+     */
+    observeLongTasks?: boolean;
+}
+/**
+ * The single rAF + longtask collector for the dashboard's frame-budget tooling.
+ * It records inter-frame deltas into a bounded rolling window and counts long
+ * tasks; `summary()` reduces them through {@link summarizeFrameSamples} so the
+ * dev overlay and the telemetry monitor read identical math. Inert until
+ * `start()`, so it costs nothing unless a caller explicitly turns it on.
+ *
+ * Pure except for the rAF/observer glue (both injectable), so it unit-tests by
+ * driving the injected rAF callback directly.
+ */
+export declare class FrameBudgetSampler {
+    private readonly windowSize;
+    private readonly budget;
+    private readonly raf;
+    private readonly cancelRaf;
+    private readonly onFrame?;
+    private readonly observeLongTasks;
+    private deltas;
+    private lastTimestamp;
+    private longTaskCount;
+    private handle;
+    private observer;
+    constructor(options?: FrameBudgetSamplerOptions);
+    get running(): boolean;
+    get longTasks(): number;
+    /** Record one frame timestamp (ms). The first sample only seeds the baseline. */
+    push(timestamp: number): void;
+    summary(): FrameBudgetSummary;
+    start(): void;
+    stop(): void;
+    /** Clear the rolling window and long-task count (start of a new time window). */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=frame-budget.d.ts.map

package/hooks/frame-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-budget.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/frame-budget.ts"],"names":[],"mappings":"AAaA,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,oBAAoB,EAAE,WAA+B,CAAC;AAEnE,oEAAoE;AACpE,wBAAgB,aAAa,CAC3B,MAAM,GAAE,WAAkC,GACzC,MAAM,CAER;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAaD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,SAAS,MAAM,EAAE,EACnC,SAAS,SAAI,EACb,MAAM,GAAE,WAAkC,GACzC,kBAAkB,CA0BpB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAST;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,OAAO,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAAK,MAAM,CAAC;AACrD,KAAK,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAE9C,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qEAAqE;IACrE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,uEAAuE;IACvE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACnE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAGf;IACV,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAoC;gBAExC,OAAO,GAAE,yBAA8B;IAoBnD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,iFAAiF;IACjF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAU7B,OAAO,IAAI,kBAAkB;IAI7B,KAAK,IAAI,IAAI;IAsBb,IAAI,IAAI,IAAI;IASZ,iFAAiF;IACjF,KAAK,IAAI,IAAI;CAKd"}

package/hooks/frame-budget.js

@@ -0,0 +1,183 @@
+// Frame-budget measurement for the dashboard shell (issue #9141, task 1).
+//
+// The render-telemetry stack (useRenderGuard / RenderTelemetryProfiler) detects
+// runaway *render loops* — too many React commits per second. It says nothing
+// about *dropped frames*: a single expensive layout/paint or a main-thread long
+// task blows the 60/120fps budget without ever tripping a commit-rate threshold.
+// This module is the missing measurement — a pure summarizer over a window of
+// requestAnimationFrame deltas plus PerformanceObserver('longtask') counts, so
+// the live HUD and any KPI spec can read the same numbers from the same math.
+//
+// Everything here is pure and deterministic (no rAF, no DOM) so it unit-tests
+// cleanly; the rAF/observer glue lives in ./useFrameBudgetMonitor.
+export const DEFAULT_FRAME_BUDGET = { targetFps: 60 };
+/** The per-frame budget in milliseconds for a target frame rate. */
+export function frameBudgetMs(budget = DEFAULT_FRAME_BUDGET) {
+    return 1000 / budget.targetFps;
+}
+const EMPTY_SUMMARY = (budgetMs) => ({
+    sampleCount: 0,
+    fps: 0,
+    meanFrameMs: 0,
+    p95FrameMs: 0,
+    worstFrameMs: 0,
+    droppedFrames: 0,
+    longTasks: 0,
+    budgetMs,
+});
+/**
+ * Nearest-rank percentile over an unsorted sample set. `p` is a fraction in
+ * (0, 1]; an empty set yields 0. Deterministic — no interpolation, so the same
+ * samples always yield the same number (stable for snapshot/KPI assertions).
+ */
+export function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const clampedP = Math.min(1, Math.max(0, p));
+    const rank = Math.ceil(clampedP * sorted.length);
+    const index = Math.min(sorted.length - 1, Math.max(0, rank - 1));
+    return sorted[index];
+}
+/**
+ * Reduce a window of frame durations into a budget summary. `frameDurationsMs`
+ * is the list of inter-frame deltas (ms); `longTasks` is the count of long-task
+ * entries seen in the same window.
+ */
+export function summarizeFrameSamples(frameDurationsMs, longTasks = 0, budget = DEFAULT_FRAME_BUDGET) {
+    const budgetMs = frameBudgetMs(budget);
+    // Ignore non-finite / negative deltas (tab-switch gaps, clock skew) — they are
+    // not real frames and would otherwise poison the mean and worst-frame stats.
+    const samples = frameDurationsMs.filter((delta) => Number.isFinite(delta) && delta >= 0);
+    if (samples.length === 0) {
+        return { ...EMPTY_SUMMARY(budgetMs), longTasks };
+    }
+    const total = samples.reduce((sum, delta) => sum + delta, 0);
+    const meanFrameMs = total / samples.length;
+    const worstFrameMs = samples.reduce((max, delta) => Math.max(max, delta), 0);
+    const droppedFrames = samples.filter((delta) => delta > budgetMs).length;
+    return {
+        sampleCount: samples.length,
+        fps: meanFrameMs > 0 ? 1000 / meanFrameMs : 0,
+        meanFrameMs,
+        p95FrameMs: percentile(samples, 0.95),
+        worstFrameMs,
+        droppedFrames,
+        longTasks,
+        budgetMs,
+    };
+}
+/**
+ * Whether a window's summary is bad enough to surface (HUD highlight / telemetry
+ * event). Kept separate from the math so the threshold policy is testable and
+ * the HUD and a KPI spec can apply the same rule.
+ */
+export function shouldReportFrameBudget(summary, options = {}) {
+    if (summary.sampleCount === 0)
+        return false;
+    const p95Factor = Math.max(1, options.p95BudgetFactor ?? 1.25);
+    const droppedRatio = options.droppedFrameRatio ?? 0.1;
+    const reportOnLongTask = options.reportOnLongTask ?? true;
+    if (reportOnLongTask && summary.longTasks > 0)
+        return true;
+    if (summary.p95FrameMs > summary.budgetMs * p95Factor)
+        return true;
+    return summary.droppedFrames / summary.sampleCount >= droppedRatio;
+}
+/**
+ * The single rAF + longtask collector for the dashboard's frame-budget tooling.
+ * It records inter-frame deltas into a bounded rolling window and counts long
+ * tasks; `summary()` reduces them through {@link summarizeFrameSamples} so the
+ * dev overlay and the telemetry monitor read identical math. Inert until
+ * `start()`, so it costs nothing unless a caller explicitly turns it on.
+ *
+ * Pure except for the rAF/observer glue (both injectable), so it unit-tests by
+ * driving the injected rAF callback directly.
+ */
+export class FrameBudgetSampler {
+    windowSize;
+    budget;
+    raf;
+    cancelRaf;
+    onFrame;
+    observeLongTasks;
+    deltas = [];
+    lastTimestamp = null;
+    longTaskCount = 0;
+    handle = null;
+    observer = null;
+    constructor(options = {}) {
+        this.windowSize = Math.max(1, options.windowSize ?? 120);
+        this.budget = options.budget ?? DEFAULT_FRAME_BUDGET;
+        this.onFrame = options.onFrame;
+        this.observeLongTasks = options.observeLongTasks ?? true;
+        this.raf =
+            options.raf ??
+                ((cb) => typeof requestAnimationFrame === "function"
+                    ? requestAnimationFrame(cb)
+                    : 0);
+        this.cancelRaf =
+            options.cancelRaf ??
+                ((handle) => {
+                    if (typeof cancelAnimationFrame === "function") {
+                        cancelAnimationFrame(handle);
+                    }
+                });
+    }
+    get running() {
+        return this.handle !== null;
+    }
+    get longTasks() {
+        return this.longTaskCount;
+    }
+    /** Record one frame timestamp (ms). The first sample only seeds the baseline. */
+    push(timestamp) {
+        if (this.lastTimestamp !== null) {
+            this.deltas.push(timestamp - this.lastTimestamp);
+            if (this.deltas.length > this.windowSize) {
+                this.deltas.splice(0, this.deltas.length - this.windowSize);
+            }
+        }
+        this.lastTimestamp = timestamp;
+    }
+    summary() {
+        return summarizeFrameSamples(this.deltas, this.longTaskCount, this.budget);
+    }
+    start() {
+        if (this.handle !== null)
+            return;
+        if (this.observeLongTasks && typeof PerformanceObserver === "function") {
+            try {
+                this.observer = new PerformanceObserver((list) => {
+                    this.longTaskCount += list.getEntries().length;
+                });
+                this.observer.observe({ entryTypes: ["longtask"] });
+            }
+            catch {
+                // `longtask` is unsupported in some engines (notably Safari) — feature
+                // detection at the boundary; frame deltas still measure framerate.
+                this.observer = null;
+            }
+        }
+        const tick = (now) => {
+            this.push(now);
+            this.onFrame?.(now, this);
+            this.handle = this.raf(tick);
+        };
+        this.handle = this.raf(tick);
+    }
+    stop() {
+        if (this.handle !== null) {
+            this.cancelRaf(this.handle);
+            this.handle = null;
+        }
+        this.observer?.disconnect();
+        this.observer = null;
+    }
+    /** Clear the rolling window and long-task count (start of a new time window). */
+    reset() {
+        this.deltas = [];
+        this.lastTimestamp = null;
+        this.longTaskCount = 0;
+    }
+}