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

package/widgets/home-attention-store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Home-attention store (#9143).
+ *
+ * Data-driven home widgets (calendar, goals, finances, health, …) carry their
+ * urgency in their *own* fetched data — an overdrawn balance, an at-risk goal,
+ * an event starting in 10 minutes — not in the shared activity-event or
+ * notification streams the home ranker reads. This store is the seam that lets
+ * such a widget feed its current importance back to the ranker: the widget
+ * publishes a weight while the attention-worthy condition holds and clears it
+ * otherwise; {@link WidgetHost} merges these into `rankHomeWidgets` so the
+ * widget floats up by *its own* state.
+ *
+ * Unlike activity/notification signals, a self-published weight represents a
+ * *sustained state* (the balance is still negative), so it must NOT decay —
+ * the store holds only `widgetKey → weight` and the consumer stamps `now` at
+ * read time (age 0 ⇒ full weight) until the widget clears it.
+ */
+/** A widget's current self-reported home importance (no timestamp — see file doc). */
+export interface HomeAttentionEntry {
+    /** `${pluginId}/${id}` of the publishing widget. */
+    widgetKey: string;
+    /** Sustained importance weight (higher = more urgent). */
+    weight: number;
+}
+/** Publish (or update) a widget's sustained home-attention weight. */
+export declare function publishHomeAttention(widgetKey: string, weight: number): void;
+/** Clear a widget's home-attention (the condition no longer holds / unmounted). */
+export declare function clearHomeAttention(widgetKey: string): void;
+/** Reactive view of every widget's current self-reported home attention. */
+export declare function useHomeAttentionSignals(): HomeAttentionEntry[];
+/**
+ * Widget-side helper: publish `weight` while it's a positive number, clear it
+ * when `null`/`0`, and always clear on unmount. A widget computes its weight
+ * from its fetched data (e.g. overdrawn → escalation weight) and passes it in;
+ * passing `null` (no attention-worthy state) removes any prior boost.
+ */
+export declare function usePublishHomeAttention(widgetKey: string, weight: number | null): void;
+/** Test-only reset. */
+export declare function __resetHomeAttentionForTests(): void;
+//# sourceMappingURL=home-attention-store.d.ts.map

package/widgets/home-attention-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-attention-store.d.ts","sourceRoot":"","sources":["../../../../../src/widgets/home-attention-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAiBD,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAK5E;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAO1D;AAaD,4EAA4E;AAC5E,wBAAgB,uBAAuB,IAAI,kBAAkB,EAAE,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,IAAI,CASN;AAED,uBAAuB;AACvB,wBAAgB,4BAA4B,IAAI,IAAI,CAInD"}

package/widgets/home-attention-store.js

@@ -0,0 +1,84 @@
+/**
+ * Home-attention store (#9143).
+ *
+ * Data-driven home widgets (calendar, goals, finances, health, …) carry their
+ * urgency in their *own* fetched data — an overdrawn balance, an at-risk goal,
+ * an event starting in 10 minutes — not in the shared activity-event or
+ * notification streams the home ranker reads. This store is the seam that lets
+ * such a widget feed its current importance back to the ranker: the widget
+ * publishes a weight while the attention-worthy condition holds and clears it
+ * otherwise; {@link WidgetHost} merges these into `rankHomeWidgets` so the
+ * widget floats up by *its own* state.
+ *
+ * Unlike activity/notification signals, a self-published weight represents a
+ * *sustained state* (the balance is still negative), so it must NOT decay —
+ * the store holds only `widgetKey → weight` and the consumer stamps `now` at
+ * read time (age 0 ⇒ full weight) until the widget clears it.
+ */
+import { useEffect, useSyncExternalStore } from "react";
+let entries = {};
+let snapshot = [];
+const listeners = new Set();
+function recompute() {
+    snapshot = Object.entries(entries).map(([widgetKey, weight]) => ({
+        widgetKey,
+        weight,
+    }));
+}
+function emit() {
+    for (const listener of listeners)
+        listener();
+}
+/** Publish (or update) a widget's sustained home-attention weight. */
+export function publishHomeAttention(widgetKey, weight) {
+    if (entries[widgetKey] === weight)
+        return;
+    entries = { ...entries, [widgetKey]: weight };
+    recompute();
+    emit();
+}
+/** Clear a widget's home-attention (the condition no longer holds / unmounted). */
+export function clearHomeAttention(widgetKey) {
+    if (!(widgetKey in entries))
+        return;
+    const next = { ...entries };
+    delete next[widgetKey];
+    entries = next;
+    recompute();
+    emit();
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+function getSnapshot() {
+    return snapshot;
+}
+/** Reactive view of every widget's current self-reported home attention. */
+export function useHomeAttentionSignals() {
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/**
+ * Widget-side helper: publish `weight` while it's a positive number, clear it
+ * when `null`/`0`, and always clear on unmount. A widget computes its weight
+ * from its fetched data (e.g. overdrawn → escalation weight) and passes it in;
+ * passing `null` (no attention-worthy state) removes any prior boost.
+ */
+export function usePublishHomeAttention(widgetKey, weight) {
+    useEffect(() => {
+        if (weight == null || weight <= 0) {
+            clearHomeAttention(widgetKey);
+            return;
+        }
+        publishHomeAttention(widgetKey, weight);
+        return () => clearHomeAttention(widgetKey);
+    }, [widgetKey, weight]);
+}
+/** Test-only reset. */
+export function __resetHomeAttentionForTests() {
+    entries = {};
+    snapshot = [];
+    listeners.clear();
+}

package/widgets/home-priority.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Home-widget priority ranking (#9143).
+ *
+ * The frontpage/home surface must NOT render every `home`-slot widget — it
+ * should surface only the highest-importance widgets *right now*, the way a
+ * phone home screen bubbles up what needs attention. This module is the pure
+ * ranking core: it scores each home widget by a stable base priority plus any
+ * recent attention/activity signals (decayed by recency), then returns the
+ * top-N ordered by current importance.
+ *
+ * It is deliberately decoupled from React and from how signals are sourced:
+ * callers (the home WidgetHost) map their live `ActivityEvent` stream into
+ * {@link HomeWidgetSignal}s and pass `now` in, so the function is pure and
+ * deterministic (no `Date.now()` in a render path — see the UI determinism
+ * gate). The signal→widget attribution and event-stream wiring live in the
+ * consumer, not here.
+ */
+import type { PluginWidgetDeclaration } from "./types.js";
+/** Minimal declaration shape the ranking needs (decoupled from the full type). */
+export type RankableHomeWidget = Pick<PluginWidgetDeclaration, "id" | "pluginId" | "order" | "signalKinds">;
+/** A live importance signal attributed to a single home widget. */
+export interface HomeWidgetSignal {
+    /** `${pluginId}/${id}` of the widget this signal boosts. */
+    widgetKey: string;
+    /** Raw importance weight (higher = more urgent). */
+    weight: number;
+    /** Epoch-ms when the signal occurred — used for recency decay. */
+    timestamp: number;
+}
+export interface RankHomeWidgetsOptions {
+    /** Current time (epoch-ms). Passed in for determinism + testability. */
+    now: number;
+    /** Maximum widgets the home surface shows. Default 6. */
+    maxVisible?: number;
+    /** Half-life of an attention signal's boost, in ms. Default 30 min. */
+    signalHalfLifeMs?: number;
+    /** Signals at or beyond this age contribute nothing. Default 6 h. */
+    signalMaxAgeMs?: number;
+    /**
+     * Minimum score a widget must reach to be shown. Default 0 (keep every
+     * declared widget, capped to `maxVisible`). Raise it above the maximum base
+     * score (1) to require live attention — i.e. hide widgets that are merely
+     * declared but have no recent activity.
+     */
+    minScore?: number;
+}
+export interface RankedHomeWidget<D extends RankableHomeWidget> {
+    declaration: D;
+    /** Combined base-priority + decayed-attention score (higher = shown first). */
+    score: number;
+}
+/**
+ * Default importance weights for the common activity/attention event types a
+ * consumer maps into {@link HomeWidgetSignal}s. Exported so the home WidgetHost
+ * (and tests) share one notion of "how urgent is this kind of event" rather
+ * than re-deriving it. Unknown event types should fall back to `activity`.
+ */
+export declare const HOME_SIGNAL_WEIGHTS: Readonly<Record<string, number>>;
+/** Resolve an event type to its importance weight (falls back to `activity`). */
+export declare function homeSignalWeight(eventType: string): number;
+/** The stable widget key used to attribute signals to a declaration. */
+export declare function homeWidgetKey(decl: RankableHomeWidget): string;
+/**
+ * Stable base importance derived from the declaration `order` (lower order =
+ * higher base), normalized to roughly `[0, 1]` so a single fresh attention
+ * signal outranks base ordering but base still breaks ties between cold
+ * widgets. `order` defaults to 100 (the registry default).
+ */
+export declare function baseHomeScore(order: number | undefined): number;
+/**
+ * Current importance of one home widget: stable base priority plus the sum of
+ * its recent attention signals, each decayed by how long ago it fired.
+ */
+export declare function scoreHomeWidget(decl: RankableHomeWidget, signals: readonly HomeWidgetSignal[], opts: RankHomeWidgetsOptions): number;
+/**
+ * Rank home widgets by current importance and return only the top-N. Ordering
+ * is descending by score; ties break deterministically by widget key so the
+ * home surface never reshuffles equal-importance widgets between renders.
+ */
+export declare function rankHomeWidgets<D extends RankableHomeWidget>(declarations: readonly D[], signals: readonly HomeWidgetSignal[], opts: RankHomeWidgetsOptions): RankedHomeWidget<D>[];
+/**
+ * Raw activity-event `eventType` → canonical signal kind (a key of
+ * {@link HOME_SIGNAL_WEIGHTS}). The activity stream uses a wider vocabulary than
+ * the weight table; this reconciles it (e.g. `proactive-message → message`).
+ * Unmapped types fall through to `activity` (weight 1).
+ */
+export declare const EVENT_TYPE_TO_SIGNAL_KIND: Readonly<Record<string, string>>;
+/** Map a raw activity-event type to its canonical signal kind. */
+export declare function signalKindForEventType(eventType: string): string;
+/** Notification inbox priority → signal kind (so urgent notifications rank like escalations). */
+export declare const NOTIFICATION_PRIORITY_TO_SIGNAL_KIND: Readonly<Record<string, string>>;
+/** Notification priority → numeric rank (higher = more urgent). */
+export declare const NOTIFICATION_PRIORITY_RANK: Readonly<Record<string, number>>;
+/** Minimal notification shape the content ranker needs. */
+export interface RankableContentNotification {
+    priority?: string;
+    /** Epoch-ms when created. */
+    createdAt: number;
+    /** Epoch-ms when read; unread (null/absent) ranks ahead of read. */
+    readAt?: number | null;
+}
+/**
+ * Order notifications inside a home widget by attention: unread before read,
+ * then higher priority, then most-recent first. Stable (equal items keep their
+ * original relative order) and pure (no `Date.now()`), so the home widget never
+ * reshuffles equal-importance items between renders.
+ */
+export declare function rankHomeNotifications<T extends RankableContentNotification>(items: readonly T[]): T[];
+/** Minimal activity-event shape the signal derivation needs. */
+export interface RankableActivityEvent {
+    eventType: string;
+    timestamp: number;
+}
+/** Minimal notification shape the signal derivation needs. */
+export interface RankableNotification {
+    priority?: string;
+    /** Epoch-ms the notification was created. */
+    timestamp: number;
+    /** Whether the user has already seen it — read items don't boost. */
+    readAt?: string | number | null;
+}
+/**
+ * Attribute each activity event to every home widget whose `signalKinds`
+ * includes the event's canonical kind, producing recency-stamped signals the
+ * ranker decays. A widget with no `signalKinds` is never boosted (ranks by
+ * static `order` only).
+ */
+export declare function homeSignalsFromEvents(events: readonly RankableActivityEvent[], declarations: readonly RankableHomeWidget[]): HomeWidgetSignal[];
+/**
+ * Attribute unread notifications to every home widget that subscribes to the
+ * notification's priority-derived kind (always at least `notification`, so a
+ * widget can opt in with `signalKinds: ["notification"]` to react to any
+ * notification regardless of priority).
+ */
+export declare function homeSignalsFromNotifications(notifications: readonly RankableNotification[], declarations: readonly RankableHomeWidget[]): HomeWidgetSignal[];
+//# sourceMappingURL=home-priority.d.ts.map

package/widgets/home-priority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-priority.d.ts","sourceRoot":"","sources":["../../../../../src/widgets/home-priority.ts"],"names":[],"mappings":"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"}

package/widgets/home-priority.js

@@ -0,0 +1,276 @@
+/**
+ * Home-widget priority ranking (#9143).
+ *
+ * The frontpage/home surface must NOT render every `home`-slot widget — it
+ * should surface only the highest-importance widgets *right now*, the way a
+ * phone home screen bubbles up what needs attention. This module is the pure
+ * ranking core: it scores each home widget by a stable base priority plus any
+ * recent attention/activity signals (decayed by recency), then returns the
+ * top-N ordered by current importance.
+ *
+ * It is deliberately decoupled from React and from how signals are sourced:
+ * callers (the home WidgetHost) map their live `ActivityEvent` stream into
+ * {@link HomeWidgetSignal}s and pass `now` in, so the function is pure and
+ * deterministic (no `Date.now()` in a render path — see the UI determinism
+ * gate). The signal→widget attribution and event-stream wiring live in the
+ * consumer, not here.
+ */
+const DEFAULT_MAX_VISIBLE = 6;
+const DEFAULT_HALF_LIFE_MS = 30 * 60_000;
+const DEFAULT_MAX_AGE_MS = 6 * 60 * 60_000;
+/**
+ * Default importance weights for the common activity/attention event types a
+ * consumer maps into {@link HomeWidgetSignal}s. Exported so the home WidgetHost
+ * (and tests) share one notion of "how urgent is this kind of event" rather
+ * than re-deriving it. Unknown event types should fall back to `activity`.
+ */
+export const HOME_SIGNAL_WEIGHTS = {
+    blocked: 10,
+    escalation: 10,
+    approval: 9,
+    reminder: 6,
+    message: 5,
+    "check-in": 4,
+    nudge: 3,
+    workflow: 2,
+    activity: 1,
+};
+/** Resolve an event type to its importance weight (falls back to `activity`). */
+export function homeSignalWeight(eventType) {
+    return HOME_SIGNAL_WEIGHTS[eventType] ?? HOME_SIGNAL_WEIGHTS.activity;
+}
+/** The stable widget key used to attribute signals to a declaration. */
+export function homeWidgetKey(decl) {
+    return `${decl.pluginId}/${decl.id}`;
+}
+/**
+ * Stable base importance derived from the declaration `order` (lower order =
+ * higher base), normalized to roughly `[0, 1]` so a single fresh attention
+ * signal outranks base ordering but base still breaks ties between cold
+ * widgets. `order` defaults to 100 (the registry default).
+ */
+export function baseHomeScore(order) {
+    const resolved = typeof order === "number" && Number.isFinite(order) ? order : 100;
+    return Math.max(0, 100 - resolved) / 100;
+}
+function recencyMultiplier(ageMs, halfLifeMs, maxAgeMs) {
+    const age = ageMs < 0 ? 0 : ageMs; // a future-stamped signal counts as "now"
+    if (age >= maxAgeMs)
+        return 0;
+    return 0.5 ** (age / halfLifeMs);
+}
+/**
+ * Current importance of one home widget: stable base priority plus the sum of
+ * its recent attention signals, each decayed by how long ago it fired.
+ */
+export function scoreHomeWidget(decl, signals, opts) {
+    const halfLife = opts.signalHalfLifeMs ?? DEFAULT_HALF_LIFE_MS;
+    const maxAge = opts.signalMaxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const key = homeWidgetKey(decl);
+    let attention = 0;
+    for (const signal of signals) {
+        if (signal.widgetKey !== key)
+            continue;
+        attention +=
+            signal.weight *
+                recencyMultiplier(opts.now - signal.timestamp, halfLife, maxAge);
+    }
+    return baseHomeScore(decl.order) + attention;
+}
+/**
+ * Rank home widgets by current importance and return only the top-N. Ordering
+ * is descending by score; ties break deterministically by widget key so the
+ * home surface never reshuffles equal-importance widgets between renders.
+ */
+export function rankHomeWidgets(declarations, signals, opts) {
+    const maxVisible = opts.maxVisible ?? DEFAULT_MAX_VISIBLE;
+    const minScore = opts.minScore ?? 0;
+    return declarations
+        .map((declaration) => ({
+        declaration,
+        key: homeWidgetKey(declaration),
+        score: scoreHomeWidget(declaration, signals, opts),
+    }))
+        .filter((entry) => entry.score >= minScore)
+        .sort((a, b) => b.score - a.score || a.key.localeCompare(b.key))
+        .slice(0, Math.max(0, maxVisible))
+        .map(({ declaration, score }) => ({ declaration, score }));
+}
+// ---------------------------------------------------------------------------
+// Live signal derivation — turn the app's activity-event stream and the
+// notification inbox into {@link HomeWidgetSignal}s attributed to the home
+// widgets that subscribe to each signal kind. This is the seam that makes the
+// pure ranker live: the home WidgetHost calls these to feed `rankHomeWidgets`.
+// Kept pure + deterministic (timestamps + `now` flow in from the caller).
+// ---------------------------------------------------------------------------
+/**
+ * Raw activity-event `eventType` → canonical signal kind (a key of
+ * {@link HOME_SIGNAL_WEIGHTS}). The activity stream uses a wider vocabulary than
+ * the weight table; this reconciles it (e.g. `proactive-message → message`).
+ * Unmapped types fall through to `activity` (weight 1).
+ */
+export const EVENT_TYPE_TO_SIGNAL_KIND = {
+    blocked: "blocked",
+    escalation: "escalation",
+    approval: "approval",
+    reminder: "reminder",
+    message: "message",
+    "proactive-message": "message",
+    "check-in": "check-in",
+    nudge: "nudge",
+    workflow: "workflow",
+    // Orchestrator lifecycle/tool events are workflow signals so active runs can
+    // lift the owning home widget without needing a separate attention publish.
+    // `error` stays at workflow strength too: AcpService emits `error` SessionEvents
+    // liberally for transient/recoverable failures (auth prompts, ENOENT, transport
+    // hiccups, mid-stream ACP errors), so routing every one to the weight-10 blocked
+    // escalation rail would manufacture false top-of-home alarms. Genuine "act now"
+    // urgency is already carried by the orchestrator's dedicated `blocked` SessionEvent.
+    task_registered: "workflow",
+    task_complete: "workflow",
+    stopped: "workflow",
+    tool_running: "workflow",
+    blocked_auto_resolved: "workflow",
+    error: "workflow",
+    warning: "workflow",
+    run_start: "workflow",
+    run_end: "workflow",
+    step_start: "workflow",
+    step_end: "workflow",
+    context_loaded: "workflow",
+    action_start: "workflow",
+    action_complete: "workflow",
+    action_error: "workflow",
+    action_skipped: "workflow",
+    tool_call: "workflow",
+    tool_result: "workflow",
+    tool_error: "workflow",
+    evaluator_start: "workflow",
+    evaluator_complete: "workflow",
+    evaluator_error: "workflow",
+    evaluator_skipped: "workflow",
+    provider_start: "workflow",
+    provider_complete: "workflow",
+    provider_error: "workflow",
+    provider_cached: "workflow",
+    assistant_thought: "workflow",
+    assistant_plan: "workflow",
+    assistant_reflection: "workflow",
+    message_received: "message",
+    message_sent: "message",
+    message_queued: "message",
+    message_failed: "workflow",
+    memory_create: "activity",
+    memory_update: "activity",
+    memory_delete: "activity",
+    memory_search: "activity",
+    memory_retrieved: "activity",
+};
+/** Map a raw activity-event type to its canonical signal kind. */
+export function signalKindForEventType(eventType) {
+    return EVENT_TYPE_TO_SIGNAL_KIND[eventType] ?? "activity";
+}
+/** Notification inbox priority → signal kind (so urgent notifications rank like escalations). */
+export const NOTIFICATION_PRIORITY_TO_SIGNAL_KIND = {
+    urgent: "escalation",
+    high: "approval",
+    normal: "message",
+    low: "activity",
+};
+// ---------------------------------------------------------------------------
+// Content-item priority *within* a single home widget (#9143). A "default" home
+// widget (notifications/messages/activity) shows a capped list, and the items
+// themselves carry priority — so the widget must surface the most
+// attention-worthy items first, not merely the most recent. This is the
+// content-level analogue of the widget-level ranker above. Pure + stable
+// (no clock; ties resolve by original order).
+// ---------------------------------------------------------------------------
+/** Notification priority → numeric rank (higher = more urgent). */
+export const NOTIFICATION_PRIORITY_RANK = {
+    urgent: 3,
+    high: 2,
+    normal: 1,
+    low: 0,
+};
+/**
+ * Order notifications inside a home widget by attention: unread before read,
+ * then higher priority, then most-recent first. Stable (equal items keep their
+ * original relative order) and pure (no `Date.now()`), so the home widget never
+ * reshuffles equal-importance items between renders.
+ */
+export function rankHomeNotifications(items) {
+    return items
+        .map((item, index) => ({ item, index }))
+        .sort((a, b) => {
+        const aUnread = a.item.readAt ? 0 : 1;
+        const bUnread = b.item.readAt ? 0 : 1;
+        if (aUnread !== bUnread)
+            return bUnread - aUnread;
+        const aPriority = NOTIFICATION_PRIORITY_RANK[a.item.priority ?? "normal"] ?? 1;
+        const bPriority = NOTIFICATION_PRIORITY_RANK[b.item.priority ?? "normal"] ?? 1;
+        if (aPriority !== bPriority)
+            return bPriority - aPriority;
+        if (a.item.createdAt !== b.item.createdAt) {
+            return b.item.createdAt - a.item.createdAt;
+        }
+        return a.index - b.index;
+    })
+        .map((entry) => entry.item);
+}
+/**
+ * Attribute each activity event to every home widget whose `signalKinds`
+ * includes the event's canonical kind, producing recency-stamped signals the
+ * ranker decays. A widget with no `signalKinds` is never boosted (ranks by
+ * static `order` only).
+ */
+export function homeSignalsFromEvents(events, declarations) {
+    const signals = [];
+    for (const event of events) {
+        const kind = signalKindForEventType(event.eventType);
+        const weight = homeSignalWeight(kind);
+        for (const decl of declarations) {
+            if (!decl.signalKinds?.includes(kind))
+                continue;
+            signals.push({
+                widgetKey: homeWidgetKey(decl),
+                weight,
+                timestamp: event.timestamp,
+            });
+        }
+    }
+    return signals;
+}
+/**
+ * Attribute unread notifications to every home widget that subscribes to the
+ * notification's priority-derived kind (always at least `notification`, so a
+ * widget can opt in with `signalKinds: ["notification"]` to react to any
+ * notification regardless of priority).
+ */
+export function homeSignalsFromNotifications(notifications, declarations) {
+    const signals = [];
+    for (const notification of notifications) {
+        if (notification.readAt)
+            continue;
+        const priorityKind = NOTIFICATION_PRIORITY_TO_SIGNAL_KIND[notification.priority ?? "normal"] ??
+            "message";
+        const kinds = new Set([priorityKind, "notification"]);
+        for (const decl of declarations) {
+            // A widget can subscribe to both the generic `notification` kind and the
+            // priority-specific kind; use the strongest matching weight so an urgent
+            // notification ranks at escalation strength rather than the generic floor.
+            let weight = 0;
+            for (const k of decl.signalKinds ?? []) {
+                if (kinds.has(k))
+                    weight = Math.max(weight, homeSignalWeight(k));
+            }
+            if (weight === 0)
+                continue;
+            signals.push({
+                widgetKey: homeWidgetKey(decl),
+                weight,
+                timestamp: notification.timestamp,
+            });
+        }
+    }
+    return signals;
+}

package/widgets/index.d.ts

@@ -1,8 +1,11 @@
-export type { WidgetPluginState } from "./registry";
-export { BUILTIN_WIDGET_DECLARATIONS, getWidgetComponent, registerBuiltinWidgetDeclarations, registerBuiltinWidgets, registerWidgetComponent, resolveWidgetsForSlot, } from "./registry";
-export { seedLegacyWidgets } from "./registry-store";
-export type { PluginWidgetDeclaration, WidgetProps, WidgetRegistration, WidgetSlot, } from "./types";
-export type { WidgetHostProps, WidgetUiActionEventDetail } from "./WidgetHost";
-export { WidgetHost } from "./WidgetHost";
-export { WIDGET_UI_ACTION_EVENT } from "./WidgetHost.constants";
+export { baseHomeScore, HOME_SIGNAL_WEIGHTS, type HomeWidgetSignal, homeSignalWeight, homeWidgetKey, type RankableHomeWidget, type RankedHomeWidget, type RankHomeWidgetsOptions, rankHomeWidgets, scoreHomeWidget, } from "./home-priority.js";
+export type { ResolvedWidget, WidgetPluginState } from "./registry.js";
+export { BUILTIN_WIDGET_DECLARATIONS, DEFAULT_WIDGET_SINK_COMPONENT, getWidgetComponent, registerBuiltinWidgetDeclarations, registerBuiltinWidgets, registerWidgetComponent, resolveWidgetsForSlot, } from "./registry.js";
+export type { PluginWidgetDeclaration, WidgetProps, WidgetRegistration, WidgetSlot, } from "./types.js";
+export type { WidgetVisibilityHook } from "./useChatSidebarVisibility.js";
+export { useWidgetVisibility } from "./useChatSidebarVisibility.js";
+export { isWidgetVisible, widgetVisibilityKey, widgetVisibilityStorageKey, } from "./visibility.js";
+export type { WidgetHostProps, WidgetUiActionEventDetail } from "./WidgetHost.js";
+export { WidgetHost } from "./WidgetHost.js";
+export { WIDGET_UI_ACTION_EVENT } from "./WidgetHost.constants.js";
 //# sourceMappingURL=index.d.ts.map

package/widgets/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/widgets/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,iCAAiC,EACjC,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EACV,uBAAuB,EACvB,WAAW,EACX,kBAAkB,EAClB,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/widgets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,EAClB,iCAAiC,EACjC,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,uBAAuB,EACvB,WAAW,EACX,kBAAkB,EAClB,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/widgets/index.js

@@ -1,4 +1,6 @@
-export { BUILTIN_WIDGET_DECLARATIONS, getWidgetComponent, registerBuiltinWidgetDeclarations, registerBuiltinWidgets, registerWidgetComponent, resolveWidgetsForSlot, } from "./registry.js";
-export { seedLegacyWidgets } from "./registry-store.js";
+export { baseHomeScore, HOME_SIGNAL_WEIGHTS, homeSignalWeight, homeWidgetKey, rankHomeWidgets, scoreHomeWidget, } from "./home-priority.js";
+export { BUILTIN_WIDGET_DECLARATIONS, DEFAULT_WIDGET_SINK_COMPONENT, getWidgetComponent, registerBuiltinWidgetDeclarations, registerBuiltinWidgets, registerWidgetComponent, resolveWidgetsForSlot, } from "./registry.js";
+export { useWidgetVisibility } from "./useChatSidebarVisibility.js";
+export { isWidgetVisible, widgetVisibilityKey, widgetVisibilityStorageKey, } from "./visibility.js";
 export { WidgetHost } from "./WidgetHost.js";
 export { WIDGET_UI_ACTION_EVENT } from "./WidgetHost.constants.js";

package/widgets/registry-store.d.ts

@@ -1,6 +1,6 @@
 import type { ComponentType } from "react";
-import type { ChatSidebarWidgetDefinition } from "../components/chat/widgets/types";
-import type { WidgetProps } from "./types";
+import type { ChatSidebarWidgetDefinition } from "../components/chat/widgets/types.js";
+import type { WidgetProps } from "./types.js";
 /**
  * Register a bundled React component for a widget declaration.
  * Key format: `${pluginId}/${declarationId}`.
@@ -9,15 +9,13 @@ export declare function registerWidgetComponent(pluginId: string, declarationId:
 /** Look up a registered component. */
 export declare function getWidgetComponent(pluginId: string, declarationId: string): ComponentType<WidgetProps> | undefined;
 /**
- * Adapts existing ChatSidebarWidgetDefinition[] to the new registry format.
- * These legacy widgets used `ChatSidebarWidgetProps` which is compatible with
- * `WidgetProps` (events + clearEvents).
- */
-export declare function seedLegacyWidgets(definitions: ReadonlyArray<ChatSidebarWidgetDefinition>): void;
-/**
- * Public API for plugins outside app-core to seed their own widget components.
- * Call this when your plugin loads (e.g. via side-effect import of a widgets
- * module). Each definition must be a `ChatSidebarWidgetDefinition`.
+ * Register bundled widget React components from `ChatSidebarWidgetDefinition[]`.
+ * `ChatSidebarWidgetProps` is structurally compatible with `WidgetProps`
+ * (events + clearEvents).
+ *
+ * This is the public API for plugins outside app-core to register their own
+ * widget components — call it when the plugin loads (e.g. via a side-effect
+ * import of a widgets module).
  */
 export declare function registerBuiltinWidgets(definitions: ReadonlyArray<ChatSidebarWidgetDefinition>): void;
 //# sourceMappingURL=registry-store.d.ts.map

package/widgets/registry-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-store.d.ts","sourceRoot":"","sources":["../../../../../src/widgets/registry-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAS3C;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,GACpC,IAAI,CAEN;AAED,sCAAsC;AACtC,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB,aAAa,CAAC,WAAW,CAAC,GAAG,SAAS,CAExC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,aAAa,CAAC,2BAA2B,CAAC,GACtD,IAAI,CAQN;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,aAAa,CAAC,2BAA2B,CAAC,GACtD,IAAI,CAEN"}
+{"version":3,"file":"registry-store.d.ts","sourceRoot":"","sources":["../../../../../src/widgets/registry-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAS3C;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,GACpC,IAAI,CAEN;AAED,sCAAsC;AACtC,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB,aAAa,CAAC,WAAW,CAAC,GAAG,SAAS,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,aAAa,CAAC,2BAA2B,CAAC,GACtD,IAAI,CAQN"}

package/widgets/registry-store.js

@@ -15,20 +15,16 @@ export function getWidgetComponent(pluginId, declarationId) {
     return getComponentRegistry().get(`${pluginId}/${declarationId}`);
 }
 /**
- * Adapts existing ChatSidebarWidgetDefinition[] to the new registry format.
- * These legacy widgets used `ChatSidebarWidgetProps` which is compatible with
- * `WidgetProps` (events + clearEvents).
+ * Register bundled widget React components from `ChatSidebarWidgetDefinition[]`.
+ * `ChatSidebarWidgetProps` is structurally compatible with `WidgetProps`
+ * (events + clearEvents).
+ *
+ * This is the public API for plugins outside app-core to register their own
+ * widget components — call it when the plugin loads (e.g. via a side-effect
+ * import of a widgets module).
  */
-export function seedLegacyWidgets(definitions) {
+export function registerBuiltinWidgets(definitions) {
     for (const def of definitions) {
         registerWidgetComponent(def.pluginId, def.id, def.Component);
     }
 }
-/**
- * Public API for plugins outside app-core to seed their own widget components.
- * Call this when your plugin loads (e.g. via side-effect import of a widgets
- * module). Each definition must be a `ChatSidebarWidgetDefinition`.
- */
-export function registerBuiltinWidgets(definitions) {
-    seedLegacyWidgets(definitions);
-}