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

package/widgets/WidgetHost.js

@@ -4,16 +4,21 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  *
  * Drop this into any page view:
  *   <WidgetHost slot="chat-sidebar" />
- *   <WidgetHost slot="wallet" />
+ *   <WidgetHost slot="home" layout="grid" />
  *
  * Queries the widget registry for matching declarations, wraps each in an
  * error boundary, and renders either the bundled React component or falls back
  * to the declarative UiRenderer for uiSpec widgets.
  */
-import { Component, useMemo } from "react";
+import { isViewVisible } from "@elizaos/core";
+import { Component, useMemo, useRef, } from "react";
 import { UiRenderer } from "../components/config-ui/ui-renderer.js";
-import { useApp } from "../state/index.js";
-import { useIsDeveloperMode } from "../state/useDeveloperMode.js";
+import { useNow } from "../hooks/useNow.js";
+import { useAppSelectorShallow } from "../state/index.js";
+import { useNotifications } from "../state/notifications/notification-store.js";
+import { useEnabledViewKinds } from "../state/useViewKinds.js";
+import { useHomeAttentionSignals } from "./home-attention-store.js";
+import { homeSignalsFromEvents, homeSignalsFromNotifications, homeWidgetKey, rankHomeWidgets, } from "./home-priority.js";
 import { resolveWidgetsForSlot } from "./registry.js";
 import { WIDGET_UI_ACTION_EVENT } from "./WidgetHost.constants.js";
 function dispatchWidgetUiAction(declaration, action, params) {
@@ -43,33 +48,147 @@ class WidgetErrorBoundary extends Component {
         return this.props.children;
     }
 }
-export function WidgetHost({ slot, events, clearEvents, className, hideWhenEmpty = true, filter, }) {
-    const { plugins } = useApp();
-    const developerModeEnabled = useIsDeveloperMode();
+// -- WidgetHost --------------------------------------------------------------
+/**
+ * Safety bound on home cards. The home surface ranks every declared widget by
+ * importance and renders them in order; each widget self-hides (renders `null`)
+ * when it has nothing attention-worthy, so the *visible* count is naturally
+ * small. This cap is just a guard against a pathological all-active state.
+ */
+const HOME_RENDER_CAP = 12;
+const WIDGET_SLOTS = new Set([
+    "chat-sidebar",
+    "character",
+    "nav-page",
+    "home",
+]);
+function isWidgetSlot(value) {
+    return WIDGET_SLOTS.has(value);
+}
+export function WidgetHost({ slot, events, clearEvents, className, layout = "stack", hideWhenEmpty = true, filter, }) {
+    const plugins = useAppSelectorShallow((s) => s.plugins);
+    const enabledKinds = useEnabledViewKinds();
+    // Live importance inputs for the home ranker. Subscribed unconditionally
+    // (hooks can't be conditional) but only consumed for the `home` slot below.
+    const { notifications } = useNotifications();
+    const selfAttention = useHomeAttentionSignals();
+    const now = useNow();
+    const serverDeclarations = useMemo(() => {
+        return (plugins ?? []).flatMap((plugin) => (plugin.widgets ?? []).flatMap((widget) => {
+            if (!isWidgetSlot(widget.slot))
+                return [];
+            return [
+                {
+                    ...widget,
+                    pluginId: widget.pluginId || plugin.id,
+                    slot: widget.slot,
+                },
+            ];
+        }));
+    }, [plugins]);
     const resolved = useMemo(() => {
-        const all = resolveWidgetsForSlot(slot, plugins ?? []);
-        const gated = developerModeEnabled
-            ? all
-            : all.filter((entry) => entry.declaration.developerOnly !== true);
+        const all = resolveWidgetsForSlot(slot, plugins ?? [], serverDeclarations);
+        const gated = all.filter((entry) => isViewVisible(entry.declaration, enabledKinds));
         return filter ? gated.filter((entry) => filter(entry.declaration)) : gated;
-    }, [slot, plugins, filter, developerModeEnabled]);
-    if (resolved.length === 0 && hideWhenEmpty)
+    }, [slot, plugins, serverDeclarations, filter, enabledKinds]);
+    // Notification → signal inputs, memoized so the `now` tick (which re-runs the
+    // component) doesn't rebuild this array each minute — it changes only when the
+    // inbox itself changes.
+    const notificationSignalInputs = useMemo(() => notifications.map((n) => ({
+        priority: n.priority,
+        timestamp: n.createdAt,
+        readAt: n.readAt,
+    })), [notifications]);
+    // The home surface ranks every declared widget by current importance and
+    // renders them in that order; each widget self-hides (renders `null`) when it
+    // has nothing attention-worthy, so the visible set is naturally focused
+    // (#9143). Importance = a stable base priority (declaration `order`) plus:
+    //  - decayed signals derived from the live activity stream + unread inbox,
+    //    attributed to widgets whose `signalKinds` subscribe to that kind, and
+    //  - sustained self-published attention (a widget floating itself up on its
+    //    own data, e.g. an overdrawn balance), stamped `now` so it doesn't decay.
+    // `now` comes from `useNow` (0 on first render, real clock in an effect) so
+    // the render path never calls `Date.now()`. Other slots render every resolved
+    // widget unchanged.
+    const ranked = useMemo(() => {
+        if (slot !== "home")
+            return resolved;
+        const renderable = resolved.filter((entry) => !entry.defaultWidgetSink);
+        const declarations = renderable.map((entry) => entry.declaration);
+        const signals = [
+            ...homeSignalsFromEvents(events ?? [], declarations),
+            ...homeSignalsFromNotifications(notificationSignalInputs, declarations),
+            ...selfAttention.map((entry) => ({ ...entry, timestamp: now })),
+        ];
+        const byKey = new Map(renderable.map((entry) => [homeWidgetKey(entry.declaration), entry]));
+        return rankHomeWidgets(declarations, signals, {
+            now,
+            maxVisible: HOME_RENDER_CAP,
+        }).flatMap((ranked) => {
+            const entry = byKey.get(homeWidgetKey(ranked.declaration));
+            return entry ? [entry] : [];
+        });
+    }, [slot, resolved, events, notificationSignalInputs, selfAttention, now]);
+    // `ranked` is recomputed on every `now` tick (decay math depends on `now`),
+    // but the rendered *set and order* only change at discrete thresholds. Keep
+    // the array reference stable across ticks that don't reorder: derive an
+    // order-key from the resolved widget keys and only swap `displayed` when that
+    // key changes. This stops the `.map` below — and therefore the widget
+    // children — from rebuilding every minute when nothing moved (#9304). Order
+    // still updates the instant a signal changes the ranking.
+    const orderKey = ranked
+        .map(({ declaration }) => homeWidgetKey(declaration))
+        .join("|");
+    const displayedRef = useRef({ key: orderKey, resolved, entries: ranked });
+    // Refresh the held set when the order changes OR when the resolved widgets
+    // change identity (a plugin reload could keep the order but swap a
+    // declaration/Component). A bare `now` tick changes neither, so the reference
+    // — and the rendered children below — stay stable.
+    if (displayedRef.current.key !== orderKey ||
+        displayedRef.current.resolved !== resolved) {
+        displayedRef.current = { key: orderKey, resolved, entries: ranked };
+    }
+    const displayed = displayedRef.current.entries;
+    const pluginById = useMemo(() => {
+        const map = new Map();
+        for (const p of plugins ?? [])
+            map.set(p.id, p);
+        return map;
+    }, [plugins]);
+    // The fields every widget shares this render — split out so the per-item props
+    // object is built from one stable base rather than re-derived inline.
+    const widgetPropsBase = useMemo(() => ({ events, clearEvents, slot }), [events, clearEvents, slot]);
+    // The rendered children, memoized on the stable order-key + the stable prop
+    // inputs. A `now` tick that doesn't reorder leaves every dependency unchanged,
+    // so this memo returns the SAME element array and the widget children never
+    // re-render (locked by WidgetHost.render-storm.test.tsx). It rebuilds only
+    // when the order, the resolved set, the plugin snapshot, or the shared props
+    // actually change.
+    const children = useMemo(() => displayed
+        .map(({ declaration, Component }) => {
+        const widgetKey = `${declaration.pluginId}/${declaration.id}`;
+        const widgetProps = {
+            ...widgetPropsBase,
+            pluginId: declaration.pluginId,
+            pluginState: pluginById.get(declaration.pluginId),
+        };
+        if (Component) {
+            return (_jsx(WidgetErrorBoundary, { widgetId: widgetKey, children: _jsx(Component, { ...widgetProps }) }, widgetKey));
+        }
+        if (declaration.uiSpec) {
+            return (_jsx(WidgetErrorBoundary, { widgetId: widgetKey, children: _jsx("div", { className: "min-w-0", "data-testid": `widget-uispec-${declaration.id}`, children: _jsx(UiRenderer, { spec: declaration.uiSpec, onAction: (action, params) => dispatchWidgetUiAction(declaration, action, params) }) }) }, widgetKey));
+        }
+        return null;
+    })
+        .filter((node) => node !== null), [displayed, widgetPropsBase, pluginById]);
+    if (children.length === 0 && hideWhenEmpty)
         return null;
-    return (_jsx("div", { className: `flex flex-col gap-3 ${className ?? ""}`, "data-testid": `widget-host-${slot}`, "data-slot": slot, children: resolved.map(({ declaration, Component }) => {
-            const widgetKey = `${declaration.pluginId}/${declaration.id}`;
-            const pluginState = (plugins ?? []).find((p) => p.id === declaration.pluginId);
-            const widgetProps = {
-                pluginId: declaration.pluginId,
-                pluginState,
-                events,
-                clearEvents,
-            };
-            if (Component) {
-                return (_jsx(WidgetErrorBoundary, { widgetId: widgetKey, children: _jsx(Component, { ...widgetProps }) }, widgetKey));
-            }
-            if (declaration.uiSpec) {
-                return (_jsx(WidgetErrorBoundary, { widgetId: widgetKey, children: _jsx("div", { className: "min-w-0", "data-testid": `widget-uispec-${declaration.id}`, children: _jsx(UiRenderer, { spec: declaration.uiSpec, onAction: (action, params) => dispatchWidgetUiAction(declaration, action, params) }) }) }, widgetKey));
-            }
-            return null;
-        }) }));
+    const layoutClass = layout === "grid"
+        ? "grid grid-cols-1 gap-3 sm:grid-cols-2"
+        : "flex flex-col gap-3";
+    return (_jsx("div", { 
+        // `contain: layout` (CSS containment): a widget reorder/resize repaints
+        // within this host and never reflows the surrounding page, so a ranking
+        // change doesn't jump the whole home (#9304).
+        className: `${layoutClass} ${className ?? ""}`, style: { contain: "layout" }, "data-testid": `widget-host-${slot}`, "data-layout": layout, "data-slot": slot, children: children }));
 }

package/widgets/__fixtures__/home-widget-mock-data.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Browser-safe mock data + installers for the home-slot WidgetHost (#9143).
+ *
+ * One source of truth for "the home dashboard, populated with attention-worthy
+ * data" — shared between the home-screen e2e fixture and the Storybook story so
+ * both render the REAL per-plugin home widgets (calendar / goals / finances /
+ * health / relationships / inbox) plus notifications, fed by injected DATA only
+ * (no stubbing of WidgetHost or the widget components).
+ *
+ * NO node imports — this is bundled into a browser IIFE (e2e) and into the
+ * Storybook renderer (vite). Times are RELATIVE to `Date.now()` so the calendar
+ * card lands inside its 2h urgent window and the bills land within a week,
+ * matching the live ranking the home surface performs.
+ *
+ * The payload shapes mirror packages/app/test/ui-smoke/home-widget-priority.spec.ts
+ * and were verified field-by-field against each widget's parser.
+ */
+import type { AgentNotification } from "@elizaos/core";
+import type { PluginInfo } from "../../api/client-types-config.js";
+export declare const HOME_WIDGET_MOCK_PLUGINS: PluginInfo[];
+/** RelationshipsAttentionWidget reads client.getRelationshipsPeople() ->
+ *  GET /api/relationships/people ({ data, stats }) and
+ *  client.getRelationshipsCandidates() -> GET /api/relationships/candidates
+ *  ({ data }). A pending merge candidate floats up at approval weight. */
+declare function relationshipsPeople(): {
+    data: {
+        groupId: string;
+        primaryEntityId: string;
+        memberEntityIds: string[];
+        displayName: string;
+        aliases: never[];
+        platforms: string[];
+        identities: never[];
+        emails: never[];
+        phones: never[];
+        websites: never[];
+        preferredCommunicationChannel: null;
+        categories: never[];
+        tags: never[];
+        factCount: number;
+        relationshipCount: number;
+        isOwner: boolean;
+        profiles: never[];
+        lastInteractionAt: string;
+    }[];
+    stats: {
+        totalPeople: number;
+        totalRelationships: number;
+        totalIdentities: number;
+    };
+};
+declare function relationshipsCandidates(): {
+    data: {
+        id: string;
+        entityA: string;
+        entityB: string;
+        confidence: number;
+        evidence: {
+            platform: string;
+            handle: string;
+        };
+        status: string;
+        proposedAt: string;
+    }[];
+};
+/** NotificationsWidget reads the notification store (hydrated from
+ *  GET /api/notifications). An urgent unread notification ranks at the top. */
+export declare const HOME_WIDGET_MOCK_NOTIFICATION: AgentNotification;
+export declare function homeWidgetRelationshipsPeople(): {
+    people: ReturnType<typeof relationshipsPeople>["data"];
+    stats: ReturnType<typeof relationshipsPeople>["stats"];
+};
+export declare function homeWidgetRelationshipsCandidates(): ReturnType<typeof relationshipsCandidates>["data"];
+export declare function homeWidgetNotificationsResponse(): {
+    notifications: AgentNotification[];
+    unreadCount: number;
+};
+/**
+ * Override `window.fetch` to answer the home widgets' data requests with the
+ * mock payloads above. Returns a restore function that puts the original
+ * `window.fetch` back.
+ */
+export declare function installHomeWidgetFetchMock(): () => void;
+/** Seed the app-store plugins snapshot so the per-plugin home widgets resolve. */
+export declare function seedHomeWidgetAppStore(): void;
+/** Reset + ingest the urgent notification into the notification store. */
+export declare function seedHomeWidgetNotifications(): void;
+export {};
+//# sourceMappingURL=home-widget-mock-data.d.ts.map

package/widgets/__fixtures__/home-widget-mock-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-widget-mock-data.d.ts","sourceRoot":"","sources":["../../../../../../src/widgets/__fixtures__/home-widget-mock-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAiChE,eAAO,MAAM,wBAAwB,EAAE,UAAU,EAShD,CAAC;AA0HF;;;0EAG0E;AAC1E,iBAAS,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B3B;AACD,iBAAS,uBAAuB;;;;;;;;;;;;;EAc/B;AA8BD;+EAC+E;AAC/E,eAAO,MAAM,6BAA6B,EAAE,iBAS3C,CAAC;AA6CF,wBAAgB,6BAA6B,IAAI;IAC/C,MAAM,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;IACvD,KAAK,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,OAAO,CAAC,CAAC;CACxD,CAGA;AAED,wBAAgB,iCAAiC,IAAI,UAAU,CAC7D,OAAO,uBAAuB,CAC/B,CAAC,MAAM,CAAC,CAER;AAED,wBAAgB,+BAA+B;;;EAE9C;AA0CD;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,IAAI,CAoBvD;AAiCD,kFAAkF;AAClF,wBAAgB,sBAAsB,IAAI,IAAI,CAI7C;AAED,0EAA0E;AAC1E,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}

package/widgets/__fixtures__/home-widget-mock-data.js

@@ -0,0 +1,388 @@
+/**
+ * Browser-safe mock data + installers for the home-slot WidgetHost (#9143).
+ *
+ * One source of truth for "the home dashboard, populated with attention-worthy
+ * data" — shared between the home-screen e2e fixture and the Storybook story so
+ * both render the REAL per-plugin home widgets (calendar / goals / finances /
+ * health / relationships / inbox) plus notifications, fed by injected DATA only
+ * (no stubbing of WidgetHost or the widget components).
+ *
+ * NO node imports — this is bundled into a browser IIFE (e2e) and into the
+ * Storybook renderer (vite). Times are RELATIVE to `Date.now()` so the calendar
+ * card lands inside its 2h urgent window and the bills land within a week,
+ * matching the live ranking the home surface performs.
+ *
+ * The payload shapes mirror packages/app/test/ui-smoke/home-widget-priority.spec.ts
+ * and were verified field-by-field against each widget's parser.
+ */
+import { publishAppValue, seedAppValue } from "../../state/app-store.js";
+import { __ingestNotificationForTests, __resetNotificationStoreForTests, } from "../../state/notifications/notification-store.js";
+// ---------------------------------------------------------------------------
+// Plugin snapshot — the per-plugin home widgets resolve only when the matching
+// plugin id is enabled+active in the app-store plugins snapshot
+// (registry.ts `isWidgetEnabled`). Notifications + messages are always-visible
+// core surfaces; agent-orchestrator is in the built-in fallback set. Mirrors the
+// ui-smoke spec's `pluginInfo()`.
+// ---------------------------------------------------------------------------
+function pluginInfo(id, name) {
+    return {
+        id,
+        name,
+        description: `${name} (home-widget fixture)`,
+        enabled: true,
+        isActive: true,
+        configured: true,
+        envKey: null,
+        category: "feature",
+        source: "bundled",
+        parameters: [],
+        validationErrors: [],
+        validationWarnings: [],
+    };
+}
+export const HOME_WIDGET_MOCK_PLUGINS = [
+    pluginInfo("calendar", "Calendar"),
+    pluginInfo("goals", "Goals"),
+    pluginInfo("finances", "Finances"),
+    pluginInfo("health", "Health"),
+    pluginInfo("relationships", "Relationships"),
+    // Inbox: the cross-channel unread card (inbox-unread.tsx, pluginId "inbox").
+    pluginInfo("inbox", "Inbox"),
+    pluginInfo("agent-orchestrator", "Agent Orchestrator"),
+];
+// ---------------------------------------------------------------------------
+// Relative time helpers — keep the seeded data inside each widget's live
+// attention window so the cards render AND float up.
+// ---------------------------------------------------------------------------
+const NOW = () => Date.now();
+const minutesFromNow = (m) => new Date(Date.now() + m * 60_000).toISOString();
+const hoursFromNow = (h) => new Date(Date.now() + h * 3_600_000).toISOString();
+const daysFromNow = (d) => new Date(Date.now() + d * 24 * 3_600_000).toISOString();
+// ---------------------------------------------------------------------------
+// Per-widget payloads (verified against each widget's parser).
+// ---------------------------------------------------------------------------
+/** CalendarUpcomingWidget reads /api/lifeops/calendar/feed; a timed event within
+ *  the next 2h floats up at reminder weight. */
+function calendarFeed() {
+    return {
+        events: [
+            {
+                id: "evt-soon",
+                title: "Design review",
+                startAt: minutesFromNow(45),
+                endAt: minutesFromNow(105),
+                isAllDay: false,
+                location: "Zoom",
+            },
+        ],
+    };
+}
+/** GoalsAttentionWidget reads /api/lifeops/goals; an at_risk goal floats up at
+ *  escalation weight and renders an urgent row. */
+function goalsPayload() {
+    return {
+        goals: [
+            {
+                goal: {
+                    id: "goal-at-risk",
+                    title: "Ship the release",
+                    status: "active",
+                    reviewState: "at_risk",
+                },
+                links: [],
+            },
+            {
+                goal: {
+                    id: "goal-on-track",
+                    title: "Learn Spanish",
+                    status: "active",
+                    reviewState: "on_track",
+                },
+                links: [],
+            },
+        ],
+    };
+}
+/** FinancesAlertsWidget reads /api/lifeops/money/{dashboard,recurring,sources};
+ *  netUsd < 0 (overdrawn) floats up at escalation weight. A connected source is
+ *  required for the card to render. */
+function moneyDashboard() {
+    return {
+        spending: { netUsd: -125.5 },
+        generatedAt: new Date(NOW()).toISOString(),
+    };
+}
+function moneySources() {
+    return { sources: [{ id: "src-1", status: "active", label: "Checking" }] };
+}
+function moneyRecurring() {
+    return {
+        charges: [
+            {
+                merchantNormalized: "netflix",
+                merchantDisplay: "Netflix",
+                cadence: "monthly",
+                averageAmountUsd: 15.99,
+                nextExpectedAt: daysFromNow(3),
+                category: "entertainment",
+            },
+        ],
+    };
+}
+/** HealthSleepWidget reads /api/lifeops/sleep/{history,regularity}; an
+ *  "irregular" classification floats up at check-in weight. A latest episode is
+ *  required for the card to render. */
+function sleepHistory() {
+    return {
+        episodes: [
+            {
+                startedAt: hoursFromNow(-8),
+                endedAt: hoursFromNow(-2),
+                durationMin: 345,
+            },
+        ],
+        summary: {
+            cycleCount: 6,
+            averageDurationMin: 360,
+            overnightCount: 6,
+            napCount: 0,
+            openCount: 0,
+        },
+        windowDays: 14,
+        includeNaps: true,
+    };
+}
+function sleepRegularity() {
+    return {
+        classification: "irregular",
+        sri: 41.2,
+        sampleSize: 6,
+        windowDays: 14,
+    };
+}
+/** RelationshipsAttentionWidget reads client.getRelationshipsPeople() ->
+ *  GET /api/relationships/people ({ data, stats }) and
+ *  client.getRelationshipsCandidates() -> GET /api/relationships/candidates
+ *  ({ data }). A pending merge candidate floats up at approval weight. */
+function relationshipsPeople() {
+    return {
+        data: [
+            {
+                groupId: "grp-pat",
+                primaryEntityId: "ent-pat",
+                memberEntityIds: ["ent-pat"],
+                displayName: "Pat Doe",
+                aliases: [],
+                platforms: ["discord"],
+                identities: [],
+                emails: [],
+                phones: [],
+                websites: [],
+                preferredCommunicationChannel: null,
+                categories: [],
+                tags: [],
+                factCount: 0,
+                relationshipCount: 1,
+                isOwner: false,
+                profiles: [],
+                lastInteractionAt: daysFromNow(-60),
+            },
+        ],
+        stats: { totalPeople: 1, totalRelationships: 1, totalIdentities: 1 },
+    };
+}
+function relationshipsCandidates() {
+    return {
+        data: [
+            {
+                id: "cand-1",
+                entityA: "ent-pat",
+                entityB: "ent-patrick",
+                confidence: 0.88,
+                evidence: { platform: "discord", handle: "pat#1" },
+                status: "pending",
+                proposedAt: new Date(NOW()).toISOString(),
+            },
+        ],
+    };
+}
+/** InboxUnreadWidget reads /api/lifeops/inbox; the wire shape is
+ *  { messages: [{ id, sender: { displayName }, subject, snippet, unread }] }
+ *  (see inbox-unread.tsx parseUnread). Only `unread === true` rows are kept. */
+function inboxPayload() {
+    return {
+        messages: [
+            {
+                id: "msg-1",
+                channel: "imessage",
+                sender: { displayName: "Alex Rivera" },
+                subject: "Deck for the 5pm",
+                snippet: "see you at 5, bring the deck",
+                unread: true,
+                receivedAt: minutesFromNow(-3),
+            },
+            {
+                id: "msg-2",
+                channel: "email",
+                sender: { displayName: "Acme Billing" },
+                subject: "Invoice past due",
+                snippet: "Your March invoice is overdue",
+                unread: true,
+                receivedAt: minutesFromNow(-90),
+            },
+        ],
+    };
+}
+/** NotificationsWidget reads the notification store (hydrated from
+ *  GET /api/notifications). An urgent unread notification ranks at the top. */
+export const HOME_WIDGET_MOCK_NOTIFICATION = {
+    id: "notif-urgent",
+    title: "Payment failed",
+    body: "Your card was declined for the Acme invoice.",
+    category: "system",
+    priority: "urgent",
+    source: "finances",
+    createdAt: Date.now(),
+    readAt: null,
+};
+function notificationsPayload() {
+    return {
+        notifications: [HOME_WIDGET_MOCK_NOTIFICATION],
+        unreadCount: 1,
+    };
+}
+/** NeedsAttentionWidget reads GET /api/approvals; the wire shape is
+ *  { pending: PendingUserAction[] } (see needs-attention.tsx / approval-routes).
+ *  Two pending decisions; the older one is the single datum the card shows. */
+function approvalsPayload() {
+    return {
+        pending: [
+            {
+                id: "approval-1",
+                kind: "approval",
+                title: "Send the signed contract to Acme",
+                createdAt: Date.now() - 45 * 60_000,
+                roomId: "11111111-1111-1111-1111-111111111111",
+                options: [
+                    { name: "approve", description: "Approve and send" },
+                    { name: "deny", description: "Don't send", isCancel: true },
+                ],
+            },
+            {
+                id: "approval-2",
+                kind: "approval",
+                title: "Confirm the production deploy",
+                createdAt: Date.now() - 5 * 60_000,
+                roomId: "11111111-1111-1111-1111-111111111111",
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Direct accessors for the relationships widget, which fetches via the typed
+// `client.getRelationshipsPeople()` / `client.getRelationshipsCandidates()`
+// methods rather than raw `window.fetch`. The e2e api-stub `client` delegates
+// to these; the Storybook story relies on the fetch mock below (the real client
+// fetches `/api/relationships/*` through `window.fetch`).
+// ---------------------------------------------------------------------------
+export function homeWidgetRelationshipsPeople() {
+    const payload = relationshipsPeople();
+    return { people: payload.data, stats: payload.stats };
+}
+export function homeWidgetRelationshipsCandidates() {
+    return relationshipsCandidates().data;
+}
+export function homeWidgetNotificationsResponse() {
+    return notificationsPayload();
+}
+function routeTable() {
+    const has = (needle) => (url) => url.includes(needle);
+    return [
+        { test: has("/api/lifeops/calendar/feed"), body: calendarFeed },
+        { test: has("/api/lifeops/goals"), body: goalsPayload },
+        { test: has("/api/lifeops/money/dashboard"), body: moneyDashboard },
+        { test: has("/api/lifeops/money/recurring"), body: moneyRecurring },
+        { test: has("/api/lifeops/money/sources"), body: moneySources },
+        { test: has("/api/lifeops/sleep/history"), body: sleepHistory },
+        { test: has("/api/lifeops/sleep/regularity"), body: sleepRegularity },
+        { test: has("/api/lifeops/inbox"), body: inboxPayload },
+        { test: has("/api/relationships/people"), body: relationshipsPeople },
+        {
+            test: has("/api/relationships/candidates"),
+            body: relationshipsCandidates,
+        },
+        { test: has("/api/notifications"), body: notificationsPayload },
+        { test: has("/api/approvals"), body: approvalsPayload },
+    ];
+}
+function jsonResponse(body) {
+    // A real Response (not a hand-rolled object) so it satisfies BOTH the widgets'
+    // raw `window.fetch(...).ok / .json()` and the typed `client.fetch` path
+    // (which also reads `.headers`, `.text()`, `.clone()`).
+    return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/**
+ * Override `window.fetch` to answer the home widgets' data requests with the
+ * mock payloads above. Returns a restore function that puts the original
+ * `window.fetch` back.
+ */
+export function installHomeWidgetFetchMock() {
+    if (typeof window === "undefined")
+        return () => { };
+    const original = window.fetch;
+    const routes = routeTable();
+    window.fetch = (async (input, _init) => {
+        const url = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url;
+        const route = routes.find((r) => r.test(url));
+        return jsonResponse(route ? route.body() : {});
+    });
+    return () => {
+        window.fetch = original;
+    };
+}
+// ---------------------------------------------------------------------------
+// App-store + notification seeding — the WidgetHost reads the plugins snapshot
+// from the app store (resolveWidgetsForSlot), and the notifications widget reads
+// the notification store. Seed both BEFORE first render.
+// ---------------------------------------------------------------------------
+const noop = () => { };
+/**
+ * A minimal {@link AppContextValue} carrying just the slices the home widgets
+ * read (`plugins`, `conversations`, `t`) — everything else resolves to a no-op
+ * via the Proxy, mirroring the inert proxy `useApp()` returns in tests. Built
+ * inline (no mock-providers import) to keep this module dependency-light and
+ * browser-safe for the esbuild e2e bundle.
+ */
+function homeWidgetAppValue() {
+    const base = {
+        plugins: HOME_WIDGET_MOCK_PLUGINS,
+        conversations: [],
+        t: ((key, values) => values?.defaultValue?.toString() ?? key),
+        uiLanguage: "en",
+    };
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop in target)
+                return target[prop];
+            return noop;
+        },
+    });
+}
+/** Seed the app-store plugins snapshot so the per-plugin home widgets resolve. */
+export function seedHomeWidgetAppStore() {
+    const value = homeWidgetAppValue();
+    seedAppValue(value);
+    publishAppValue(value);
+}
+/** Reset + ingest the urgent notification into the notification store. */
+export function seedHomeWidgetNotifications() {
+    __resetNotificationStoreForTests();
+    __ingestNotificationForTests(HOME_WIDGET_MOCK_NOTIFICATION, 1);
+}