gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/world-venue-map/entity-detail.tsx

@@ -0,0 +1,147 @@
+import type { RefObject } from "react";
+import type {
+  GeoColumnFormat,
+  GeoEntityPayload,
+  GeoEntityRow,
+  GeoLayerInfo,
+  GeoPropValue,
+  GeoSeriesInfo,
+  GeoTickerLink,
+} from "../../../api-client/geo";
+import { ActionRow, DetailScrollBody, KeyValueRow, Section, StatGrid, type StatItem } from "../../../components";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box, Text, type ScrollBoxRenderable } from "../../../ui";
+import { clipToDisplayWidth, displayWidth } from "../../../utils/format";
+import { formatGeoValue, isChangeColumn, tickerLinkKey } from "./layers";
+
+interface EntityDetailProps {
+  layer: GeoLayerInfo;
+  row: GeoEntityRow | null;
+  detail: GeoEntityPayload | null;
+  /** The entity's series, main one first. */
+  series: readonly GeoSeriesInfo[];
+  width: number;
+  now: number;
+  scrollRef: RefObject<ScrollBoxRenderable | null>;
+  onOpenTicker: (link: GeoTickerLink) => void;
+  onOpenSeries: (series: GeoSeriesInfo) => void;
+}
+
+const SHORT_KEYS = new Set(["mmsi", "imo", "iata", "icao", "id"]);
+
+/** A number stored as a code (`shipType`, `navStatus`) means nothing on its own, so the detail leaves it out. */
+function isNumericCode(key: string, value: GeoPropValue): boolean {
+  return typeof value === "number" && /(Type|Status|Code)$/.test(key);
+}
+
+/** The unit a key carries that no column format draws: metres and degrees. */
+function detailText(key: string, value: GeoPropValue, now: number): string {
+  if (typeof value === "number" && /Deg$/.test(key)) return `${Math.round(value)}°`;
+  if (typeof value === "number" && /[a-z]M$/.test(key)) return `${formatGeoValue(value, Number.isInteger(value) ? "int" : "decimal1", now)} m`;
+  return formatGeoValue(value, detailFormat(key, value), now);
+}
+
+/** Detail fields carry no column format; the server puts units in the key (`lastSeen`, `importSharePct`). */
+function detailFormat(key: string, value: GeoPropValue): GeoColumnFormat | undefined {
+  if (SHORT_KEYS.has(key.toLowerCase())) return "text";
+  if (typeof value === "string" && /(At|Seen|Time)$/.test(key)) return "datetime";
+  if (typeof value !== "number") return undefined;
+  if (/Pct$/.test(key)) return "percent1";
+  if (/Km$/.test(key)) return "km";
+  if (/Kn$/.test(key)) return "knots";
+  return Number.isInteger(value) ? "int" : "decimal1";
+}
+
+/** `lastSeen` reads "Last seen", `mmsi` reads "MMSI". */
+function humanizeKey(key: string): string {
+  if (SHORT_KEYS.has(key.toLowerCase())) return key.toUpperCase();
+  // The unit suffix moves into the value: "importSharePct" reads "Import share", "lengthM" "Length".
+  const words = key.replace(/(Pct|Km|Kn|Deg|M)$/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([a-z])(\d)/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .toLowerCase()
+    .replace(/\b(\d+)d\b/g, "$1D");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+function trailSpan(trail: GeoEntityPayload["trail"]): string | null {
+  if (!trail || trail.length < 2) return null;
+  const start = Date.parse(trail[0]![2]);
+  const end = Date.parse(trail.at(-1)![2]);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) return null;
+  const minutes = Math.round((end - start) / 60_000);
+  return minutes < 90 ? `Last ${minutes}m` : `Last ${Math.round(minutes / 60)}h`;
+}
+
+const VIA_WORDS: Record<GeoTickerLink["via"], string> = {
+  owner: "Owner",
+  operator: "Operator",
+  route: "Route",
+  sector: "Sector",
+};
+
+/** One row, one line: a label and what it is, clipped so a long note never wraps over the next row. */
+function LinkRow({ label, detail, width, onPress }: { label: string; detail: string; width: number; onPress: () => void }) {
+  const colors = useThemeColors();
+  const room = Math.max(0, width - displayWidth(label) - 3);
+  return (
+    <ActionRow label={label} onPress={onPress} width={width}>
+      {room > 3 ? <Text fg={colors.textDim}>{clipToDisplayWidth(detail, room)}</Text> : null}
+    </ActionRow>
+  );
+}
+
+/** One entity: its figures, the companies it links to, its series and the rest of its fields. */
+export function EntityDetail({ layer, row, detail, series, width, now, scrollRef, onOpenTicker, onOpenSeries }: EntityDetailProps) {
+  const props: Record<string, GeoPropValue> = { ...row?.props, ...detail?.feature.props, ...detail?.detail };
+  const columns = layer.columns.filter((column) => column.key !== "label");
+  const shown = new Set(["label", ...columns.map((column) => column.key)]);
+  const figures: StatItem[] = columns.flatMap((column) => {
+    const value = formatGeoValue(props[column.key], column.format, now, isChangeColumn(column));
+    return value ? [{ id: column.key, label: column.label, value }] : [];
+  });
+  const tickers = detail?.feature.tickers ?? row?.tickers ?? [];
+  const track = trailSpan(detail?.trail);
+  const title = row?.label ?? detail?.feature.label;
+  // The stack header already names the entity, so a `name` field that repeats it is left out.
+  const rest = Object.entries(props).filter(([key, value]) => !shown.has(key) && value !== null && value !== "" && value !== title && !isNumericCode(key, value));
+  const innerWidth = Math.max(10, width - 2);
+  const labelWidth = Math.min(16, Math.max(8, ...rest.map(([key]) => displayWidth(humanizeKey(key)) + 1), track ? 6 : 0));
+  return (
+    <DetailScrollBody ref={scrollRef} resetScrollKey={`${layer.id}:${row?.id ?? detail?.feature.id ?? ""}`}>
+      {figures.length ? <StatGrid items={figures} width={innerWidth} /> : null}
+      {tickers.length ? (
+        <Section title="Linked Tickers" width={innerWidth}>
+          {tickers.map((link) => (
+            <LinkRow
+              key={`${tickerLinkKey(link)}:${link.via}`}
+              label={link.symbol}
+              detail={[VIA_WORDS[link.via] ?? link.via, link.confidence === "inferred" ? "inferred" : null, link.note ?? null].filter(Boolean).join(" · ")}
+              width={innerWidth}
+              onPress={() => onOpenTicker(link)}
+            />
+          ))}
+        </Section>
+      ) : null}
+      {series.length ? (
+        <Section title="Series" width={innerWidth}>
+          {series.map((entry) => (
+            <LinkRow key={entry.id} label={entry.name} detail={entry.frequency} width={innerWidth} onPress={() => onOpenSeries(entry)} />
+          ))}
+        </Section>
+      ) : null}
+      {track || rest.length ? (
+        <Section title="Details" width={innerWidth}>
+          <Box flexDirection="column">
+            {track ? <KeyValueRow label="Track" value={track} width={innerWidth} labelWidth={labelWidth} /> : null}
+            {rest.map(([key, value]) => (
+              <KeyValueRow key={key} label={humanizeKey(key)} value={detailText(key, value, now)} width={innerWidth} labelWidth={labelWidth} />
+            ))}
+          </Box>
+        </Section>
+      ) : null}
+    </DetailScrollBody>
+  );
+}

package/src/plugins/builtin/world-venue-map/entity-table.ts

@@ -0,0 +1,59 @@
+/** The entity table: the layer's own columns fitted to the width, plus the linked ticker. */
+import type { GeoColumn, GeoColumnFormat, GeoEntityRow } from "../../../api-client/geo";
+import type { DataTableColumn } from "../../../components";
+import { getTableWidth } from "../../../components/ui/table-layout";
+import { columnValue, formatGeoValue, isChangeColumn, plainGeoValue } from "./layers";
+
+export const TICKER_COLUMN_ID = "__ticker";
+
+export type EntityColumn = DataTableColumn & {
+  geo: GeoColumn | null;
+};
+
+const FORMAT_WIDTH: Record<GeoColumnFormat, number> = {
+  text: 10,
+  int: 6,
+  decimal1: 6,
+  percent1: 6,
+  datetime: 7,
+  knots: 7,
+  km: 8,
+};
+
+const TICKER_WIDTH = 6;
+const MIN_LABEL_WIDTH = 14;
+
+/** A right-aligned text column is a code (an MMSI, an IMO number): kept only when there is room left. */
+function isIdentifier(column: GeoColumn): boolean {
+  return column.align === "right" && (column.format ?? "text") === "text";
+}
+
+/**
+ * The label first and the ticker last, then the layer's columns in its order
+ * while they fit, codes after everything else; a narrow pane keeps the label
+ * and the ticker.
+ */
+export function entityColumns(columns: readonly GeoColumn[], width: number): EntityColumn[] {
+  const [first, ...rest] = columns.length ? columns : [{ key: "label", label: "Name" } satisfies GeoColumn];
+  const label: EntityColumn = { id: first!.key, label: first!.label, width: MIN_LABEL_WIDTH, flexGrow: 1, align: "left", geo: first! };
+  const ticker: EntityColumn = { id: TICKER_COLUMN_ID, label: "Ticker", width: TICKER_WIDTH, align: "left", geo: null };
+  const fits = (candidate: EntityColumn[]) => getTableWidth(candidate) <= width;
+  const tail = fits([label, ticker]) ? [ticker] : [];
+  const picked = new Set<GeoColumn>();
+  const inOrder = () => rest.filter((column) => picked.has(column)).map((column): EntityColumn => ({
+    id: column.key, label: column.label, width: FORMAT_WIDTH[column.format ?? "text"], align: column.align ?? "left", geo: column,
+  }));
+  for (const column of [...rest.filter((entry) => !isIdentifier(entry)), ...rest.filter(isIdentifier)]) {
+    picked.add(column);
+    if (!fits([label, ...inOrder(), ...tail])) picked.delete(column);
+  }
+  const middle = inOrder();
+  const spare = Math.max(0, width - getTableWidth([label, ...middle, ...tail]));
+  return [{ ...label, width: MIN_LABEL_WIDTH + spare }, ...middle, ...tail];
+}
+
+/** A cell's text and the plain value an export writes. */
+export function entityCellText(row: GeoEntityRow, column: GeoColumn, now: number): { text: string; value: number | string | null } {
+  const raw = columnValue(row, column);
+  return { text: formatGeoValue(raw, column.format, now, isChangeColumn(column)), value: plainGeoValue(raw) };
+}

package/src/plugins/builtin/world-venue-map/evidence.ts

@@ -0,0 +1,77 @@
+/**
+ * What `gloomberb shot MAP <layers>` certifies: the layers the map drew and
+ * what each held, so a capture taken before the features arrived is refused.
+ */
+import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { isRecord } from "../../../utils/guards";
+import type { GeoLayerState } from "./feed";
+import { WORLD_VENUE_MAP_PANE_ID } from "./ids";
+import { parseLayerTokens } from "./layers";
+
+interface WorldMapEvidenceLayer {
+  id: string;
+  phase: GeoLayerState["phase"];
+  features: number;
+  clusters: number;
+}
+
+interface WorldMapEvidence {
+  kind: "world-map";
+  version: 1;
+  complete: boolean;
+  plottedValueCount: number;
+  tokens: string[];
+  layers: WorldMapEvidenceLayer[];
+  tableRows: number;
+}
+
+const SETTLED = new Set<GeoLayerState["phase"]>(["ready", "unavailable", "zoom", "locked", "error"]);
+
+export function useWorldMapEvidence(tokens: readonly string[], states: readonly GeoLayerState[], tableRows: number, tableLoading: boolean) {
+  useRemoteUiNode({
+    role: "chart-data",
+    label: "Rendered world map layers",
+    getMetadata: () => {
+      const layers = states.map((state) => ({ id: state.layer.id, phase: state.phase, features: state.features.length, clusters: state.clusters.length }));
+      const complete = !tableLoading && states.every((state) => SETTLED.has(state.phase) && !state.loading);
+      return {
+        kind: "world-map",
+        version: 1,
+        complete,
+        ready: complete,
+        plottedValueCount: layers.reduce((sum, layer) => sum + layer.features + layer.clusters, 0) + tableRows,
+        tokens: [...tokens],
+        layers,
+        tableRows,
+      } satisfies WorldMapEvidence & { ready: boolean };
+    },
+  });
+}
+
+function requestedTokens(request: Parameters<PaneScreenshotEvidenceHook["mismatches"]>[1]): string[] {
+  const fromOption = parseLayerTokens(request.resolved.options.layer);
+  return fromOption.length ? fromOption : parseLayerTokens(request.resolved.createOptions?.arg ?? "");
+}
+
+export const worldMapScreenshotEvidence: PaneScreenshotEvidenceHook<WorldMapEvidence> = {
+  paneId: WORLD_VENUE_MAP_PANE_ID,
+  kind: "world-map",
+  label: "world map layers",
+  read(value) {
+    if (!isRecord(value) || value.kind !== "world-map" || value.version !== 1 || typeof value.complete !== "boolean"
+      || !Number.isSafeInteger(value.plottedValueCount) || !Array.isArray(value.layers) || !Array.isArray(value.tokens)) return null;
+    return value as unknown as WorldMapEvidence;
+  },
+  mismatches(evidence, request) {
+    const asked = requestedTokens(request);
+    return asked.join(",") === evidence.tokens.join(",") ? [] : ["Map layers differ from the request"];
+  },
+  unavailable(evidence) {
+    if (!evidence) return ["world map layers"];
+    return evidence.layers.filter((layer) => layer.phase === "error").map((layer) => layer.id);
+  },
+  symbols() {
+    return [];
+  },
+};

package/src/plugins/builtin/world-venue-map/feed.ts

@@ -0,0 +1,293 @@
+/**
+ * Features for the layers on the map. Each layer asks for what the view
+ * covers, waits for the view to settle before asking again, drops an answer a
+ * newer request replaced, refreshes on its own cadence while the pane can be
+ * seen, and asks nothing below its minimum zoom or while it is unavailable.
+ */
+import { ApiRequestError } from "../../../api-client/errors";
+import {
+  getGeoFeatures,
+  GEO_FEATURE_LIMIT,
+  type GeoCluster,
+  type GeoFeature,
+  type GeoLayerInfo,
+  type GeoRequest,
+} from "../../../api-client/geo";
+import { geoViewKey, MAX_RENDERED_CLUSTERS, MAX_RENDERED_FEATURES, type GeoView } from "./layers";
+
+type GeoLayerPhase = "loading" | "ready" | "error" | "zoom" | "unavailable" | "locked";
+
+export interface GeoLayerState {
+  layer: GeoLayerInfo;
+  phase: GeoLayerPhase;
+  /** Asking for a new view (or the first one); a timed refresh stays quiet. */
+  loading: boolean;
+  features: GeoFeature[];
+  clusters: GeoCluster[];
+  truncated: boolean;
+  asOf: string | null;
+  fetchedAt: number | null;
+  error: string | null;
+  /** The server's words for a layer that cannot serve right now. */
+  note: string | null;
+}
+
+interface Timers {
+  setTimeout: (callback: () => void, ms: number) => unknown;
+  clearTimeout: (handle: unknown) => void;
+  now: () => number;
+}
+
+interface FeedEntry {
+  state: GeoLayerState;
+  /** View the drawn features (or the request in flight) belong to. */
+  key: string | null;
+  controller: AbortController | null;
+  debounce: unknown;
+  refresh: unknown;
+  /** After a 429, nothing is asked before this time. */
+  blockedUntil: number;
+}
+
+export interface GeoFeedOptions {
+  debounceMs?: number;
+  timers?: Partial<Timers>;
+  /** Whether this viewer may read a layer; a Pro layer without Pro is drawn as locked. */
+  canAccess?: (layer: GeoLayerInfo) => boolean;
+}
+
+const DEFAULT_TIMERS: Timers = {
+  setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+  clearTimeout: (handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>),
+  now: () => Date.now(),
+};
+
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException ? error.name === "AbortError" : (error as { name?: string } | null)?.name === "AbortError";
+}
+
+export class GeoLayerFeed {
+  private readonly entries = new Map<string, FeedEntry>();
+  private readonly timers: Timers;
+  private readonly debounceMs: number;
+  private readonly canAccess: (layer: GeoLayerInfo) => boolean;
+  private view: GeoView | null = null;
+  private active = true;
+  private snapshotCache: GeoLayerState[] | null = null;
+
+  constructor(
+    private readonly request: GeoRequest,
+    private readonly onChange: () => void,
+    options: GeoFeedOptions = {},
+  ) {
+    this.timers = { ...DEFAULT_TIMERS, ...options.timers };
+    this.debounceMs = options.debounceMs ?? 250;
+    this.canAccess = options.canAccess ?? (() => true);
+  }
+
+  /** The layers on, in drawing order. */
+  snapshot(): GeoLayerState[] {
+    this.snapshotCache ??= [...this.entries.values()].map((entry) => entry.state);
+    return this.snapshotCache;
+  }
+
+  update(layers: readonly GeoLayerInfo[], view: GeoView, active: boolean): void {
+    const viewChanged = !this.view || geoViewKey(this.view) !== geoViewKey(view);
+    const resumed = active && !this.active;
+    this.view = view;
+    this.active = active;
+    const ids = new Set(layers.map((layer) => layer.id));
+    for (const [id, entry] of this.entries) {
+      if (ids.has(id)) continue;
+      this.stop(entry);
+      this.entries.delete(id);
+      this.changed();
+    }
+    for (const layer of layers) {
+      const existing = this.entries.get(layer.id);
+      const entry = existing ?? this.create(layer);
+      if (!existing) this.entries.set(layer.id, entry);
+      entry.state = { ...entry.state, layer };
+      this.plan(entry, view, { fresh: !existing, viewChanged, resumed });
+    }
+    this.reorder(layers);
+    this.changed();
+  }
+
+  /** Aborts and forgets everything; a later update starts over. */
+  dispose(): void {
+    for (const entry of this.entries.values()) this.stop(entry);
+    this.entries.clear();
+    this.view = null;
+    this.snapshotCache = null;
+  }
+
+  private create(layer: GeoLayerInfo): FeedEntry {
+    return {
+      state: { layer, phase: "loading", loading: false, features: [], clusters: [], truncated: false, asOf: layer.asOf, fetchedAt: null, error: null, note: null },
+      key: null,
+      controller: null,
+      debounce: null,
+      refresh: null,
+      blockedUntil: 0,
+    };
+  }
+
+  private reorder(layers: readonly GeoLayerInfo[]): void {
+    const ordered = layers.map((layer) => [layer.id, this.entries.get(layer.id)!] as const);
+    this.entries.clear();
+    for (const [id, entry] of ordered) this.entries.set(id, entry);
+  }
+
+  private plan(entry: FeedEntry, view: GeoView, change: { fresh: boolean; viewChanged: boolean; resumed: boolean }): void {
+    const { layer } = entry.state;
+    if (layer.status === "unavailable" || !this.canAccess(layer)) {
+      this.stop(entry);
+      entry.key = null;
+      entry.state = { ...entry.state, phase: layer.status === "unavailable" ? "unavailable" : "locked", loading: false, features: [], clusters: [], truncated: false, error: null };
+      return;
+    }
+    if (layer.minZoom !== undefined && view.zoom < layer.minZoom) {
+      this.stop(entry);
+      entry.key = null;
+      entry.state = { ...entry.state, phase: "zoom", loading: false, features: [], clusters: [], truncated: false, error: null };
+      return;
+    }
+    const key = geoViewKey(view);
+    if (!this.active) {
+      // Hidden: keep what is drawn, ask nothing, and catch up on return.
+      this.clearRefresh(entry);
+      return;
+    }
+    if (entry.key === key && !change.resumed) return;
+    if (entry.key === key && change.resumed) {
+      if (this.isDue(entry)) this.fetch(entry, key, true);
+      else this.scheduleRefresh(entry);
+      return;
+    }
+    // A new view supersedes whatever was in flight for the old one.
+    this.abort(entry);
+    this.clearRefresh(entry);
+    if (entry.debounce !== null) this.timers.clearTimeout(entry.debounce);
+    entry.debounce = null;
+    entry.key = key;
+    // A layer just turned on asks at once; a moving view waits until it settles.
+    if (change.fresh || !change.viewChanged) {
+      this.fetch(entry, key);
+      return;
+    }
+    entry.state = { ...entry.state, loading: true };
+    entry.debounce = this.timers.setTimeout(() => {
+      entry.debounce = null;
+      this.fetch(entry, key);
+    }, this.debounceMs);
+  }
+
+  private isDue(entry: FeedEntry): boolean {
+    const seconds = entry.state.layer.refreshSeconds;
+    if (!seconds || entry.state.fetchedAt === null) return entry.state.fetchedAt === null;
+    return this.timers.now() - entry.state.fetchedAt >= seconds * 1000;
+  }
+
+  private fetch(entry: FeedEntry, key: string, silent = false): void {
+    const view = this.view;
+    if (!view) return;
+    this.abort(entry);
+    this.clearRefresh(entry);
+    const wait = entry.blockedUntil - this.timers.now();
+    if (wait > 0) {
+      entry.refresh = this.timers.setTimeout(() => {
+        entry.refresh = null;
+        if (entry.key === key) this.fetch(entry, key, silent);
+      }, wait);
+      return;
+    }
+    const controller = new AbortController();
+    entry.controller = controller;
+    if (!silent || entry.state.fetchedAt === null) {
+      entry.state = { ...entry.state, loading: true, phase: entry.state.fetchedAt === null ? "loading" : entry.state.phase };
+      this.changed();
+    }
+    const layerId = entry.state.layer.id;
+    getGeoFeatures(this.request, layerId, { bbox: view.bbox, zoom: view.zoom, limit: GEO_FEATURE_LIMIT }, controller.signal)
+      .then((payload) => {
+        if (controller.signal.aborted || entry.controller !== controller || entry.key !== key) return;
+        entry.controller = null;
+        // A layer the catalog listed can still answer that it cannot serve (no positions yet).
+        if (payload.status === "unavailable") {
+          entry.state = { ...entry.state, phase: "unavailable", loading: false, features: [], clusters: [], truncated: false, fetchedAt: this.timers.now(), error: null, note: payload.statusNote ?? null };
+          this.scheduleRefresh(entry);
+          this.changed();
+          return;
+        }
+        entry.state = {
+          ...entry.state,
+          phase: "ready",
+          loading: false,
+          note: payload.status === "partial" ? payload.statusNote ?? null : null,
+          features: (payload.features ?? []).slice(0, MAX_RENDERED_FEATURES),
+          clusters: (payload.clusters ?? []).slice(0, MAX_RENDERED_CLUSTERS),
+          truncated: payload.truncated === true || (payload.features?.length ?? 0) > MAX_RENDERED_FEATURES,
+          asOf: payload.asOf ?? entry.state.layer.asOf,
+          fetchedAt: this.timers.now(),
+          error: null,
+        };
+        this.scheduleRefresh(entry);
+        this.changed();
+      })
+      .catch((error: unknown) => {
+        if (controller.signal.aborted || entry.controller !== controller || isAbort(error)) return;
+        entry.controller = null;
+        if (error instanceof ApiRequestError && error.status === 403) {
+          entry.state = { ...entry.state, phase: "locked", loading: false, features: [], clusters: [], truncated: false, error: null };
+          this.changed();
+          return;
+        }
+        // Keep drawn features through a failed refresh; the footer says it failed.
+        entry.state = {
+          ...entry.state,
+          phase: entry.state.fetchedAt === null ? "error" : entry.state.phase,
+          loading: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        // Over the request limit: wait as long as the server asks before trying again.
+        const backoff = error instanceof ApiRequestError && error.status === 429 ? error.retryAfterMs ?? 30_000 : null;
+        if (backoff !== null) entry.blockedUntil = this.timers.now() + backoff;
+        this.scheduleRefresh(entry, backoff);
+        this.changed();
+      });
+  }
+
+  private scheduleRefresh(entry: FeedEntry, retryAfterMs: number | null = null): void {
+    this.clearRefresh(entry);
+    const seconds = entry.state.layer.refreshSeconds;
+    if ((!seconds && retryAfterMs === null) || !this.active) return;
+    const key = entry.key;
+    entry.refresh = this.timers.setTimeout(() => {
+      entry.refresh = null;
+      if (key && entry.key === key) this.fetch(entry, key, true);
+    }, Math.max(retryAfterMs ?? 0, (seconds ?? 0) * 1000));
+  }
+
+  private clearRefresh(entry: FeedEntry): void {
+    if (entry.refresh !== null) this.timers.clearTimeout(entry.refresh);
+    entry.refresh = null;
+  }
+
+  private abort(entry: FeedEntry): void {
+    entry.controller?.abort();
+    entry.controller = null;
+  }
+
+  private stop(entry: FeedEntry): void {
+    this.abort(entry);
+    this.clearRefresh(entry);
+    if (entry.debounce !== null) this.timers.clearTimeout(entry.debounce);
+    entry.debounce = null;
+  }
+
+  private changed(): void {
+    this.snapshotCache = null;
+    this.onChange();
+  }
+}