gloomberb 0.18.1 → 0.18.3

package/src/plugins/builtin/dividend-yield/headless.ts

@@ -15,6 +15,7 @@ import type { Quote } from "../../../types/financials";
 import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
 import { dividendPriceStatus, dividendQuotePriceMetadata } from "./reference-price";
 import { mapWithConcurrency } from "../../../utils/concurrency";
+import { logFailure } from "../../../utils/log-failure";
 import { projectDividendRanking, roundedRatio, type DividendRankingEntry } from "./ranking";
 import { REPORT_FILTER, REPORT_ROWS } from "../shared/headless-options";
 import type { FundBondFacts } from "../../../api-client/fund-facts";
@@ -50,6 +51,9 @@ export interface DividendYieldHeadlessDependencies {
   loadTreasury?(context: HeadlessPaneContext): Promise<TreasuryTenor[] | null>;
 }
 
+/** Already logged at the quote boundary; keep it distinct from absent bond facts. */
+class BondClassificationError extends Error {}
+
 const defaultDependencies: DividendYieldHeadlessDependencies = {
   async loadData(symbol, context) {
     let currentPrice: number | null = null;
@@ -63,7 +67,8 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
       currentPrice = regularSessionValuationPrice(quote);
       currentPriceCurrency = quote.currency;
       referenceQuote = quote;
-    } catch {
+    } catch (error) {
+      logFailure("dividend-yield.headless", "Read dividend reference quote failed")(error);
       currentPrice = null;
     }
     const data = await fetchDividendData(symbol, currentPrice, exchange, currentPriceCurrency);
@@ -75,7 +80,11 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
   async loadBond(symbol, context) {
     const instrument = await context.resolveInstrument?.(symbol);
     const exchange = instrument?.exchange ?? "";
-    const quote = await context.marketData.getQuote(symbol, exchange).catch(() => undefined);
+    const quote = await context.marketData.getQuote(symbol, exchange)
+      .catch((error) => {
+        logFailure("dividend-yield.headless", "Read bond fund classification quote failed")(error);
+        throw new BondClassificationError("Bond fund quote check failed");
+      });
     const venue = exchange || quote?.exchangeName || "";
     if (resolveTickerInstrumentKind(null, { quote }) !== "fund" || (venue && !isUsListingExchange(venue))) return null;
     return fetchFundBondFacts(instrument?.symbol ?? symbol, context.apiClient);
@@ -125,7 +134,7 @@ export function projectDividendYieldHeadless(
   const metrics = data.metrics;
   const currency = data.currency ?? data.payments[0]?.currency ?? "";
   const priceStatus = dividendPriceStatus(data.price, data.priceAsOf, data.priceStale);
-  const errors = [data.historyError, data.summaryError].filter((error): error is string => !!error);
+  const errors = [data.historyError, data.summaryError, tax?.checkError].filter((error): error is string => !!error);
 
   return {
     ...(errors.length > 0 ? { complete: false, errors } : {}),
@@ -249,15 +258,26 @@ export function createDividendYieldHeadless(
       // One symbol is its full report; several are one table ranked by yield.
       if (args.symbols.length <= 1) {
         const symbol = args.symbols[0] ?? String(args.argument);
+        let bondCheckError: string | undefined;
         const [data, bond, treasury] = await Promise.all([
           dependencies.loadData(symbol, context),
-          // A fund's bond facts never fail the report: without them its yields read as before.
-          dependencies.loadBond?.(symbol, context).catch(() => null) ?? null,
-          rates ? dependencies.loadTreasury?.(context).catch(() => null) ?? null : null,
+          // Optional enrichment without a tax rate; a requested tax check must distinguish failure from absence.
+          dependencies.loadBond?.(symbol, context)
+            .catch((error) => {
+              if (error instanceof BondClassificationError) {
+                bondCheckError = error.message;
+              } else {
+                logFailure("dividend-yield.headless", "Read bond fund facts for report failed")(error);
+                bondCheckError = "Bond fund facts check failed";
+              }
+              return null;
+            }) ?? null,
+          rates ? dependencies.loadTreasury?.(context)
+            .catch(logFailure("dividend-yield.headless", "Read Treasury curve for tax comparison failed", null)) ?? null : null,
         ]);
         const forward = data.metrics.lapse ? null : distributionBasis(data.metrics.forwardYield, "forward", data.metrics.forwardRateAsOf ?? null);
         const tax = rates ? analyzeTaxEquivalent({
-          symbol: symbol.toUpperCase(), bond, rates, treasury,
+          symbol: symbol.toUpperCase(), bond, rates, treasury, checkError: bondCheckError,
           distribution: forward ?? distributionBasis(data.metrics.trailingYield, "trailing"),
         }) : null;
         return projectDividendYieldHeadless(data, args, { bond, tax });
@@ -275,7 +295,9 @@ export function createDividendYieldHeadless(
       }
       const entries = await mapWithConcurrency(args.symbols, RANKING_CONCURRENCY, async (symbol): Promise<DividendRankingEntry> => {
         // A fund's bond facts never fail its row: without them it ranks as before.
-        const bond = dependencies.loadBond?.(symbol, context).catch(() => null) ?? null;
+        const bond = dependencies.loadBond?.(symbol, context)
+          .catch((error) => error instanceof BondClassificationError ? null
+            : logFailure("dividend-yield.headless", "Read bond fund facts for ranking failed", null)(error)) ?? null;
         try {
           return { symbol, data: await dependencies.loadData(symbol, context), bond: await bond };
         } catch (error) {

package/src/plugins/builtin/dividend-yield/provider-client.ts

@@ -3,6 +3,7 @@ import { regularSessionValuationPrice } from "../../../market-data/quotes/regula
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { cashInMajorUnits } from "../../../utils/dividend-cash";
 import { dividendReferencePrice } from "../../../utils/trailing-dividend";
+import { logFailure } from "../../../utils/log-failure";
 import { buildDividendMetrics, INCOMPLETE_DIVIDEND_HISTORY, MISSING_DIVIDEND_CURRENCY, toDividendPayment, type DividendData } from "./client";
 import { dividendQuotePriceMetadata } from "./reference-price";
 
@@ -17,7 +18,8 @@ export async function fetchProviderDividendData(
   if (!provider.getCorporateActions) throw new Error("Dividend history source unavailable.");
   const [sourceActions, quote] = await Promise.all([
     provider.getCorporateActions(symbol, exchange),
-    provider.getQuote(symbol, exchange).catch(() => null),
+    provider.getQuote(symbol, exchange)
+      .catch(logFailure("dividend-yield.provider-client", "Read dividend reference quote failed", null)),
   ]);
   // In the major unit as the history arrives, as the provider router serves it.
   const actions = cashInMajorUnits(sourceActions);

package/src/plugins/builtin/doe/pane.tsx

@@ -129,7 +129,7 @@ export function DoePane({ width, height, focused }: PaneProps) {
   const data = resource.data?.payload ?? null;
   // The server not serving the board yet is a state of the data, not a failure.
   const notAvailable = !data && resource.error === DOE_NOT_AVAILABLE;
-  const { strip, rows: tabRows } = usePaneTabs(data ? { tabs: [...DOE_TABS], activeValue: tab, onSelect: setTab, focused, dense: true } : null);
+  const { strip, rows: tabRows } = usePaneTabs({ tabs: [...DOE_TABS], activeValue: tab, onSelect: setTab, focused, dense: true });
   useAutoRefresh(resource.updatedAt, resource.load);
   usePaneRefreshKey(() => void resource.reload(), { focused });
   usePaneNoticeFooter({ registrationId: "doe:notices", focused,

package/src/plugins/builtin/earnings-calls/headless.ts

@@ -70,8 +70,8 @@ const defaultDependencies: EarningsCallsHeadlessDependencies = {
 };
 
 /** A refused read says what the lock note says (CALLS is Pro whole), so a free account meets the same words as a signed-out one. */
-function explainDenied(ticker: string | null) {
-  return (error: unknown): never => { throw explainRefusal(error, callsLockNote, { symbol: ticker }); };
+function explainDenied(ticker: string | null, context: HeadlessPaneContext) {
+  return async (error: unknown): Promise<never> => { throw await explainRefusal(error, callsLockNote, { symbol: ticker, context }); };
 }
 
 function callRow(call: CloudEarningsCallPayload) {
@@ -285,7 +285,7 @@ export function createEarningsCallsHeadless(
     },
     async load(args, context) {
       const ticker = typeof args.argument === "string" ? args.argument : null;
-      const calls = await dependencies.loadCalls(ticker, 200, context).catch(explainDenied(ticker));
+      const calls = await dependencies.loadCalls(ticker, 200, context).catch(explainDenied(ticker, context));
       if (!ticker || !readsTranscript(args)) {
         return projectEarningsCallsHeadless(calls, { ...args, options: { ...args.options, limit: args.options.limit ?? 50 } });
       }
@@ -299,7 +299,7 @@ export function createEarningsCallsHeadless(
         }
         throw new Error(`No ${quarter} earnings call found for ${ticker}.`);
       }
-      const transcript = await dependencies.loadTranscript(selected.id, context).catch(explainDenied(ticker));
+      const transcript = await dependencies.loadTranscript(selected.id, context).catch(explainDenied(ticker, context));
       if (isPendingTranscript(transcript)) {
         throw new Error(`Transcript for ${ticker} ${quarter} is still being produced.`);
       }

package/src/plugins/builtin/earnings-calls/lock-note.ts

@@ -1,17 +1,26 @@
 import type { PaneLock } from "../../../types/plugin";
-import { proLockNote } from "../shared/pro-lock-note";
+import { resolveHeadlessInstrument } from "../shared/headless-market-data";
+import { proLockNote, type FreeRoute } from "../shared/pro-lock-note";
+
+const EVENTS_ROUTE: FreeRoute = {
+  text: (ticker, company) => `gloomberb events ${ticker} lists ${company}'s earnings dates, with the EPS reported at each and the next estimate.`,
+  answers: async (symbol, context) => {
+    const { symbol: ticker, exchange } = await resolveHeadlessInstrument(context, symbol);
+    return ((await context.marketData.getCorporateActions?.(ticker, exchange))?.earnings.length ?? 0) > 0;
+  },
+};
 
 /**
  * CALLS is Pro whole, the list of calls included. `events` needs no account
  * and lists a company's earnings dates, each with the EPS it reported and the
  * next one's estimate, without the call or its transcript.
  */
-export function callsLockNote(lock: PaneLock): string {
+export function callsLockNote(lock: PaneLock): Promise<string> {
   return proLockNote(lock, {
     token: "CALLS",
     argument: "optional",
     does: "it reads each earnings call into a transcript with speaker turns, analyst Q&A and extracted guidance",
     shows: "it",
-    free: (ticker, company) => `gloomberb events ${ticker} lists ${company}'s earnings dates, with the EPS reported at each and the next estimate.`,
+    free: [EVENTS_ROUTE],
   });
 }

package/src/plugins/builtin/econ/calendar-model.ts

@@ -191,6 +191,37 @@ export function matchesCountry(event: EconEvent, filter: CountryFilter): boolean
   return event.country === filter;
 }
 
+/**
+ * How long after its release time a high-impact print is still news: the
+ * calendar is asked for it this long, and a print that turns up later is
+ * recorded without a toast.
+ */
+export const PRINT_PENDING_MS = 20 * 60 * 1000;
+
+/** High-impact releases whose time has come in the last {@link PRINT_PENDING_MS} and that have no actual yet. */
+export function pendingHighImpactPrints(events: readonly EconEvent[], now: number): EconEvent[] {
+  return events.filter((event) => {
+    if (event.impact !== "high" || event.actual) return false;
+    const releasedFor = now - event.date.getTime();
+    return releasedFor >= 0 && releasedFor <= PRINT_PENDING_MS;
+  });
+}
+
+export function hasPendingHighImpactPrint(events: readonly EconEvent[], now: number): boolean {
+  return pendingHighImpactPrints(events, now).length > 0;
+}
+
+/** High-impact rows that were blank in `previous` and have an actual in `next`. */
+export function landedHighImpactPrints(
+  previous: ReadonlyMap<string, string | null>,
+  next: readonly EconEvent[],
+): EconEvent[] {
+  return next.filter((event) => {
+    if (event.impact !== "high" || !event.actual || !previous.has(event.id)) return false;
+    return !previous.get(event.id);
+  });
+}
+
 export function formatCountdown(ms: number): string {
   if (ms <= 60_000) return "in <1m";
   const totalMin = Math.floor(ms / 60_000);
@@ -229,6 +260,10 @@ export function getCalendarCache(options?: { allowExpired?: boolean }): EconCale
   return cache.get(CACHE_KEY, options);
 }
 
+export function subscribeCalendar(listener: () => void): () => void {
+  return cache.subscribe(CACHE_KEY, listener);
+}
+
 export interface EconCalendarLoadResult extends EconCalendarCacheEntry {
   refreshError?: string;
 }

package/src/plugins/builtin/econ/index.tsx

@@ -20,6 +20,7 @@ import type { PluginModule } from "../plugin-module";
 import { colors, blendHex } from "../../../theme/colors";
 import type { EconEvent } from "./types";
 import { FRED_CATALOG_SERIES } from "./fred-catalog";
+import { ECON_PRINT_NOTIFICATIONS_ENABLED_KEY, retainVisiblePrintRefresh, setupHighImpactPrintNotifications } from "./print-watch";
 import { EconDetailView } from "./detail-view";
 import {
   COUNTRY_CYCLE,
@@ -35,6 +36,7 @@ import {
   formatCountdown,
   formatStaleness,
   getCalendarCache,
+  subscribeCalendar,
   impactIndicator,
   loadCalendar,
   matchesCountry,
@@ -75,10 +77,16 @@ function EconCalendarPane({ focused, width, height }: PaneProps) {
   // loadCalendar serves a fresh cache without a request, so the pane can always
   // ask and still follow the global cadence once the cache goes stale.
   const calendar = useAsyncResource<CalendarResult>(loadEvents, { initialData: cachedEvents });
+  // A load made elsewhere, such as the print watch asking while a release is
+  // due, reaches the open pane through the cache; the newer of the two wins.
+  const [cacheVersion, setCacheVersion] = useState(0);
+  useEffect(() => subscribeCalendar(() => setCacheVersion((version) => version + 1)), []);
+  const cached = useMemo(() => getCalendarCache(), [cacheVersion]);
+  const shown = cached && (!calendar.data || cached.fetchedAt > calendar.data.fetchedAt) ? cached : calendar.data;
   const { loading } = calendar;
-  const events = calendar.data?.data ?? NO_EVENTS;
-  const stale = calendar.data?.stale ?? false;
-  const fetchedAt = calendar.data?.fetchedAt ?? null;
+  const events = shown?.data ?? NO_EVENTS;
+  const stale = shown?.stale ?? false;
+  const fetchedAt = shown?.fetchedAt ?? null;
   // A cache that could not be refreshed arrives as a result, not a failure.
   const error = calendar.error ?? (loading ? null : calendar.data?.refreshError ?? null);
   // The selected row and the open event are remembered by event id, so a
@@ -94,8 +102,11 @@ function EconCalendarPane({ focused, width, height }: PaneProps) {
 
   useAutoRefresh(stale ? null : fetchedAt, calendar.load);
 
-  // Tick every 30s to update staleness + countdown, only while the pane can be seen.
   const paneVisible = usePaneVisible();
+  // In view, a due high-impact print is asked for on the print watch's timing
+  // and lands here through the cache; a covered or hidden pane asks nothing.
+  useEffect(() => (paneVisible ? retainVisiblePrintRefresh() : undefined), [paneVisible]);
+  // Tick every 30s to update staleness + countdown, only while the pane can be seen.
   useEffect(() => {
     if (!paneVisible) return;
     setNow(Date.now());
@@ -437,6 +448,8 @@ function EconCalendarPane({ focused, width, height }: PaneProps) {
   );
 }
 
+let stopPrintWatch: (() => void) | null = null;
+
 export const economicCalendarModule: PluginModule = {
   series: FRED_CATALOG_SERIES,
   panes: [{
@@ -449,6 +462,16 @@ export const economicCalendarModule: PluginModule = {
     defaultMode: "floating",
     defaultFloatingSize: { width: 100, height: 30 },
     tableExport: true,
+    settings: {
+      title: "Economic Calendar Settings",
+      fields: [{
+        key: ECON_PRINT_NOTIFICATIONS_ENABLED_KEY,
+        label: "Notifications",
+        description: "Notify when a high-impact release prints, even while this pane is closed.",
+        type: "toggle",
+        storage: "plugin",
+      }],
+    },
   }],
   paneTemplates: [{
     id: "econ-calendar-pane",
@@ -461,8 +484,12 @@ export const economicCalendarModule: PluginModule = {
   }],
   setup(ctx) {
     attachEconCalendarPersistence(ctx.persistence);
+    stopPrintWatch?.();
+    stopPrintWatch = setupHighImpactPrintNotifications(ctx);
   },
   dispose() {
+    stopPrintWatch?.();
+    stopPrintWatch = null;
     resetEconCalendarPersistence();
   },
 };

package/src/plugins/builtin/econ/print-watch.ts

@@ -0,0 +1,279 @@
+import type { GloomPluginContext } from "../../../types/plugin";
+import {
+  getCalendarCache,
+  landedHighImpactPrints,
+  loadCalendar,
+  pendingHighImpactPrints,
+  PRINT_PENDING_MS,
+  subscribeCalendar,
+  type EconCalendarCacheEntry,
+} from "./calendar-model";
+import type { EconEvent } from "./types";
+
+/** The ECO setting that turns the print toast on. Off until the user turns it on, as breaking news is. */
+export const ECON_PRINT_NOTIFICATIONS_ENABLED_KEY = "econPrintNotificationsEnabled";
+
+const TOAST_DURATION_MS = 20_000;
+/**
+ * The waits between asks while a print is due: short just after the release
+ * time, when most prints land, then longer until the window closes, which
+ * keeps a release to about twenty asks per app instead of eighty.
+ */
+const PRINT_BACKOFF_MS = [15_000, 30_000, 60_000] as const;
+/** Each wait moves by up to a fifth either way, so apps that started together drift apart. */
+const PRINT_JITTER = 0.2;
+/** How often the watch looks at the calendar it already has while nothing is due. */
+const PRINT_IDLE_MS = 60_000;
+/** While idle, a calendar this old is asked for again, so a release added since is known. */
+const CALENDAR_RECHECK_MS = 6 * 60 * 60 * 1000;
+/** With no calendar at all, how long a failed ask waits before the next. */
+const NO_CALENDAR_RETRY_MS = 5 * 60 * 1000;
+
+type CalendarRead = Pick<EconCalendarCacheEntry, "data" | "fetchedAt">;
+
+export interface PrintWatchDeps {
+  now: () => number;
+  /** Asks for the calendar; `force` skips a fresh cache. */
+  load: (force: boolean) => Promise<CalendarRead>;
+  /** The cached calendar, however old, without a request. */
+  read: () => CalendarRead | null;
+  /** Called whenever anyone, a pane included, loads the calendar. */
+  subscribe: (listener: () => void) => () => void;
+  schedule: (run: () => Promise<void> | void, delay: number) => () => void;
+  random: () => number;
+}
+
+const DEFAULT_DEPS: PrintWatchDeps = {
+  now: Date.now,
+  load: (force) => loadCalendar(force),
+  read: () => getCalendarCache({ allowExpired: true }),
+  subscribe: subscribeCalendar,
+  schedule: (run, delay) => {
+    const timer = setTimeout(run, delay);
+    return () => clearTimeout(timer);
+  },
+  random: Math.random,
+};
+
+function printBody(event: EconEvent): string {
+  return event.forecast ? `${event.event} ${event.actual} vs ${event.forecast}` : `${event.event} ${event.actual}`;
+}
+
+type PrintWatchContext = Pick<GloomPluginContext, "notify" | "showPane">;
+
+/**
+ * Toasts a high-impact print once, when it lands within
+ * {@link PRINT_PENDING_MS} of its release time. While one is due the
+ * calendar is asked for on {@link PRINT_BACKOFF_MS}, and every read is
+ * compared: the watch's own, its idle look at the cache, and a pane's
+ * refresh. The first read only records what has already printed.
+ */
+export function startHighImpactPrintWatch(
+  ctx: PrintWatchContext,
+  overrides: Partial<PrintWatchDeps> = {},
+): () => void {
+  const deps: PrintWatchDeps = { ...DEFAULT_DEPS, ...overrides };
+  let stopped = false;
+  let running = false;
+  let cancel: (() => void) | null = null;
+  /** The newest calendar the watch has seen. */
+  let latest: CalendarRead | null = null;
+  let lastAskAt = Number.NEGATIVE_INFINITY;
+  let primed = false;
+  /**
+   * Each high-impact row not yet past its window, by id: null while blank,
+   * then its number. A number stays once seen, so a print that blanks and
+   * comes back is not a new print.
+   */
+  const actuals = new Map<string, string | null>();
+  const expiries = new Map<string, number>();
+  let attempt = 0;
+  let dueIds = new Set<string>();
+
+  const toast = (event: EconEvent) => {
+    ctx.notify({
+      title: event.country,
+      body: printBody(event),
+      type: "info",
+      desktop: "always",
+      sound: "Glass",
+      duration: TOAST_DURATION_MS,
+      refId: `econ:${event.id}`,
+      action: { label: "Open", onClick: () => ctx.showPane("econ-calendar") },
+    });
+  };
+
+  /** `now` is when the read was asked for, so a print the last ask in the window brings back still counts. */
+  const observe = (read: CalendarRead | null, now = deps.now()) => {
+    if (stopped || !read) return;
+    if (!latest || read.fetchedAt >= latest.fetchedAt) latest = read;
+    const landed = primed ? landedHighImpactPrints(actuals, read.data) : [];
+    for (const event of read.data) {
+      if (event.impact !== "high") continue;
+      const expiresAt = event.date.getTime() + PRINT_PENDING_MS;
+      if (expiresAt < now) continue;
+      expiries.set(event.id, expiresAt);
+      if (event.actual) actuals.set(event.id, event.actual);
+      else if (!actuals.has(event.id)) actuals.set(event.id, null);
+    }
+    for (const [id, expiresAt] of expiries) {
+      if (expiresAt >= now) continue;
+      expiries.delete(id);
+      actuals.delete(id);
+    }
+    primed = true;
+    // A print that turns up after its window is recorded, not announced late.
+    for (const event of landed) {
+      if (now - event.date.getTime() <= PRINT_PENDING_MS) toast(event);
+    }
+  };
+
+  /** Whether a print in the newest calendar is due and still within its window. */
+  const printDue = (now: number): boolean => {
+    const pending = latest ? pendingHighImpactPrints(latest.data, now) : [];
+    // A release that has just come due starts the waits over.
+    if (pending.length === 0 || pending.some((event) => !dueIds.has(event.id))) attempt = 0;
+    dueIds = new Set(pending.map((event) => event.id));
+    return pending.length > 0;
+  };
+
+  const backoff = (): number => {
+    const base = PRINT_BACKOFF_MS[Math.min(attempt, PRINT_BACKOFF_MS.length - 1)]!;
+    attempt += 1;
+    return Math.round(base * (1 + (deps.random() * 2 - 1) * PRINT_JITTER));
+  };
+
+  const askWhileIdle = (now: number): boolean => (latest
+    ? now - Math.max(latest.fetchedAt, lastAskAt) >= CALENDAR_RECHECK_MS
+    : now - lastAskAt >= NO_CALENDAR_RETRY_MS);
+
+  const arm = (delay: number) => {
+    if (stopped || cancel) return;
+    cancel = deps.schedule(() => {
+      cancel = null;
+      return run();
+    }, delay);
+  };
+
+  const run = async () => {
+    if (stopped || running) return;
+    observe(deps.read());
+    const before = deps.now();
+    const due = printDue(before);
+    if (!due && !askWhileIdle(before)) {
+      arm(PRINT_IDLE_MS);
+      return;
+    }
+    running = true;
+    lastAskAt = before;
+    try {
+      // A due print is asked for past the cache; otherwise a fresh cache answers without a request.
+      observe(await deps.load(due), before);
+    } catch {
+      // The next ask follows the same schedule.
+    } finally {
+      running = false;
+    }
+    if (stopped) return;
+    // Past the window nothing is due, so the asks stop and the watch goes back to idle looks.
+    arm(printDue(deps.now()) ? backoff() : PRINT_IDLE_MS);
+  };
+
+  // A load the watch is waiting on is compared when it answers, at the time it was asked.
+  const unsubscribe = deps.subscribe(() => {
+    if (!running) observe(deps.read());
+  });
+  void run();
+  return () => {
+    stopped = true;
+    unsubscribe();
+    cancel?.();
+    cancel = null;
+  };
+}
+
+type PrintNotificationContext = PrintWatchContext & Pick<GloomPluginContext, "configState" | "on">;
+
+function printNotificationsEnabled(ctx: Pick<GloomPluginContext, "configState">): boolean {
+  return ctx.configState.get<boolean>(ECON_PRINT_NOTIFICATIONS_ENABLED_KEY) === true;
+}
+
+/**
+ * The one print watch, run while anything wants it: the Notifications
+ * setting, or an ECO pane in view, which fills a print in as it lands. Every
+ * reason shares its timing and its requests; only the setting toasts.
+ */
+export interface PrintRefresh {
+  /** The plugin's context, for toasts and their Open; null once it is disposed. */
+  attach(ctx: PrintWatchContext | null): void;
+  setNotifying(on: boolean): void;
+  /** An ECO pane can be seen; the returned release says it no longer can. */
+  retainVisiblePane(): () => void;
+}
+
+export function createPrintRefresh(
+  start: (ctx: PrintWatchContext) => () => void = startHighImpactPrintWatch,
+): PrintRefresh {
+  let host: PrintWatchContext | null = null;
+  let notifying = false;
+  let visiblePanes = 0;
+  let stopWatch: (() => void) | null = null;
+  // A print that lands while only a pane wants the watch is recorded, not toasted.
+  const watchContext: PrintWatchContext = {
+    notify: (notice) => {
+      if (notifying) host?.notify(notice);
+    },
+    showPane: (paneId) => host?.showPane(paneId),
+  };
+  const sync = () => {
+    const wanted = notifying || visiblePanes > 0;
+    if (wanted && !stopWatch) stopWatch = start(watchContext);
+    if (!wanted && stopWatch) {
+      stopWatch();
+      stopWatch = null;
+    }
+  };
+  return {
+    attach(ctx) {
+      host = ctx;
+    },
+    setNotifying(on) {
+      notifying = on;
+      sync();
+    },
+    retainVisiblePane() {
+      visiblePanes += 1;
+      sync();
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        visiblePanes -= 1;
+        sync();
+      };
+    },
+  };
+}
+
+const printRefresh = createPrintRefresh();
+
+/** For the ECO pane: while it can be seen, a due high-impact print is asked for on the watch's timing. */
+export function retainVisiblePrintRefresh(): () => void {
+  return printRefresh.retainVisiblePane();
+}
+
+/** Toasts prints while the Notifications setting is on; off, only a pane in view keeps the watch asking. */
+export function setupHighImpactPrintNotifications(
+  ctx: PrintNotificationContext,
+  refresh: PrintRefresh = printRefresh,
+): () => void {
+  refresh.attach(ctx);
+  const sync = () => refresh.setNotifying(printNotificationsEnabled(ctx));
+  const disposeConfigListener = ctx.on("config:changed", sync);
+  sync();
+  return () => {
+    disposeConfigListener();
+    refresh.setNotifying(false);
+    refresh.attach(null);
+  };
+}