gloomberb 0.15.2 → 0.15.3

package/src/utils/double-escape-close.ts

@@ -17,30 +17,8 @@ export function resetDoubleEscapeClose(state: DoubleEscapeCloseState) {
   state.targetId = null;
 }
 
-export function recordDoubleEscapeClose(
-  state: DoubleEscapeCloseState,
-  targetId: string | null | undefined,
-  now: number,
-  thresholdMs = DOUBLE_ESCAPE_CLOSE_MS,
-): boolean {
-  if (!targetId) {
-    resetDoubleEscapeClose(state);
-    return false;
-  }
-
-  const matched = state.targetId === targetId && now - state.lastAt <= thresholdMs;
-  if (matched) {
-    resetDoubleEscapeClose(state);
-    return true;
-  }
-
-  state.targetId = targetId;
-  state.lastAt = now;
-  return false;
-}
-
 /**
- * Split form for key handling: `take` runs before the pane and closes on the
+ * Key handling for a double-Esc close: `take` runs before the pane and closes on the
  * second Esc of a pair, `arm` runs after it and only when nothing used the Esc.
  * So an Esc that backs out of a detail or closes a menu never counts as the
  * first half of a close.

package/src/utils/errors.ts

@@ -0,0 +1,4 @@
+/** The message of a thrown Error, or the thrown value as text. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/utils/exchanges.ts

@@ -237,6 +237,16 @@ export function canonicalExchange(value?: string): string {
   return CANONICAL_EXCHANGE_ALIASES[normalized] ?? normalized;
 }
 
+/**
+ * The US primary listing venues, as canonical exchanges. All of them trade the
+ * US regular and extended-hours sessions.
+ */
+export const US_LISTING_EXCHANGES: ReadonlySet<string> = new Set(["NASDAQ", "NYSE", "AMEX", "ARCA", "BATS"]);
+
+export function isUsListingExchange(value?: string): boolean {
+  return US_LISTING_EXCHANGES.has(canonicalExchange(value));
+}
+
 export function resolveExchangeTimeZone(value?: string): string | null {
   const canonical = canonicalExchange(value);
   return canonical ? EXCHANGE_TIME_ZONES[canonical] ?? null : null;

package/src/utils/financial-statements.ts

@@ -1,9 +1,6 @@
 import type { FinancialStatement } from "../types/financials";
 import { copyIncomeField, incomeFieldOwner, INCOME_STATEMENT_FIELDS, isIncomeStatementField } from "./income-statement";
-import { hasStatementWithdrawals, mergeStatementWithdrawals, redactWithdrawnStatement } from "./statement-observations";
-import { mergeStatementOperatingResult, normalizeStatementOperatingResult, reportedOperatingCohort, REPORTED_OPERATING_FIELDS } from "./operating-result";
-import { EARNINGS_FIELDS, mergeReportedEarningsResult, ownedReportedEarningsCohort } from "./reported-earnings-result";
-import { normalizeStatementEarningsResult } from "./earnings-result";
+import { mergeStatementGaps } from "./statement-gaps";
 
 export const FINANCIAL_VINTAGE_NOTICE = "Latest available statements may include restatements. Historical as-of values are not reconstructed.";
 export const SEC_EPS_BASIS_NOTICE = "SEC EPS uses corroborated split-adjusted share bases. Unverified bases are unavailable.";
@@ -13,12 +10,6 @@ const NEARBY_PERIOD_END_MS = 7 * 24 * 60 * 60 * 1_000;
 
 /** An explicit field map is authoritative: omitted fields have unknown availability. */
 export function statementFieldAvailability(row: FinancialStatement | undefined, field: string): string | undefined {
-  if (REPORTED_OPERATING_FIELDS.includes(field as typeof REPORTED_OPERATING_FIELDS[number])) {
-    const reported = reportedOperatingCohort(row);
-    if (reported) return reported.filed;
-  }
-  const earnings = ownedReportedEarningsCohort(row);
-  if (earnings && EARNINGS_FIELDS.includes(field as typeof EARNINGS_FIELDS[number])) return earnings.filed;
   const filed = isIncomeStatementField(field) ? row?.fieldSources?.[field]?.filed : undefined;
   const value = filed ?? (row?.fieldAvailability !== undefined ? row.fieldAvailability?.[field] : row?.availableAt);
   return value && Number.isFinite(Date.parse(value)) ? value : undefined;
@@ -86,8 +77,6 @@ function hasMatchingFinancialValues(left: FinancialStatement, right: FinancialSt
 }
 
 function isVerifiedCalendarAlias(left: FinancialStatement, right: FinancialStatement): boolean {
-  if (hasStatementWithdrawals(left) || hasStatementWithdrawals(right)) return false;
-  if (left.operatingResult || right.operatingResult || left.earningsResult || right.earningsResult) return false;
   if (left.date === right.date || left.date.slice(0, 7) !== right.date.slice(0, 7)) return false;
   const monthEnd = (row: FinancialStatement) => {
     const date = new Date(`${row.date}T00:00:00Z`);
@@ -124,8 +113,6 @@ function matchFallbackRow(
   return fallbackRows
     .flatMap((row) => {
       if (usedFallbackRows.has(row)) return [];
-      if (hasStatementWithdrawals(primary) || hasStatementWithdrawals(row)) return [];
-      if (primary.operatingResult || row.operatingResult || primary.earningsResult || row.earningsResult) return [];
       const fallbackTime = statementDateTime(row);
       if (fallbackTime === null) return [];
       const distance = Math.abs(fallbackTime - primaryTime);
@@ -138,8 +125,8 @@ export function mergeFinancialStatementRows(
   primaryRows: FinancialStatement[],
   fallbackRows: FinancialStatement[],
 ): FinancialStatement[] {
-  primaryRows = coalesceFinancialPeriodAliases(primaryRows.map(row => normalizeStatementEarningsResult(normalizeStatementOperatingResult(redactWithdrawnStatement(row)))));
-  fallbackRows = coalesceFinancialPeriodAliases(fallbackRows.map(row => normalizeStatementEarningsResult(normalizeStatementOperatingResult(redactWithdrawnStatement(row)))));
+  primaryRows = coalesceFinancialPeriodAliases(primaryRows);
+  fallbackRows = coalesceFinancialPeriodAliases(fallbackRows);
   if (primaryRows.length === 0) return fallbackRows;
   if (fallbackRows.length === 0) return primaryRows;
 
@@ -149,14 +136,13 @@ export function mergeFinancialStatementRows(
     if (fallback) usedFallbackRows.add(fallback);
     // Keep the preferred report intact when providers use different reporting currencies.
     if (row.currency && fallback?.currency && row.currency !== fallback.currency) return row;
-    let merged = {
+    const merged = {
       ...fallback,
       ...row,
       // Prefer the date backed by filing provenance. Generic provider merges
       // otherwise retain their primary provider's period identity.
       date: canonicalStatementDate(row, fallback),
     } as FinancialStatement;
-    mergeStatementWithdrawals(merged, [row, ...(fallback ? [fallback] : [])]);
     const correctedFallbackEps = !row.epsBasis && !!fallback?.epsBasis && row.eps === fallback.epsBasis.originalValue;
     if (row.eps !== undefined && !row.epsBasis && !correctedFallbackEps) delete merged.epsBasis;
     // Period provenance belongs to the selected date. It must not leak from a
@@ -225,15 +211,10 @@ export function mergeFinancialStatementRows(
       }
     }
 
+    // A gap either report declares for the period survives the other's value.
+    mergeStatementGaps(merged, [row, fallback]);
     // A fallback row-level date cannot safely date a different primary value.
     // Retained fallback fields still carry their own per-field provenance.
-    mergeStatementOperatingResult(merged, row, fallback);
-    const reported = reportedOperatingCohort(merged);
-    if (reported) for (const field of REPORTED_OPERATING_FIELDS) fieldAvailability[field] = reported.filed;
-    mergeReportedEarningsResult(merged, [row, ...(fallback ? [fallback] : [])]);
-    const earnings = ownedReportedEarningsCohort(merged);
-    if (earnings) for (const field of EARNINGS_FIELDS) fieldAvailability[field] = earnings.filed;
-    merged = redactWithdrawnStatement(merged);
     for (const key of keys) if (!hasMetricValue(merged, key)) delete fieldAvailability[key];
     const retainedMetricKeys = keys.filter((key) => hasMetricValue(merged, key));
     const availableAt = completeAvailability(retainedMetricKeys.map((key) => fieldAvailability[key]));

package/src/utils/format.ts

@@ -1,5 +1,3 @@
-import { toTimestampMillis } from "./timestamp";
-
 const currencyFormatters = new Map<string, Intl.NumberFormat>();
 const numberFormatters = new Map<number, Intl.NumberFormat>();
 
@@ -132,6 +130,12 @@ export function formatNumber(value: number | undefined, decimals = 2): string {
   return getNumberFormatter(decimals).format(value);
 }
 
+/** A percentile rank with its window: "73 pctl 1Y", "-- pctl 1Y" when unranked, "73 pctl" without a window. */
+export function formatPercentileRank(value: number | null | undefined, window?: string): string {
+  const rank = value == null || !Number.isFinite(value) ? "--" : value.toFixed(0);
+  return window ? `${rank} pctl ${window}` : `${rank} pctl`;
+}
+
 /** Format a growth rate compactly (e.g., +12%, -5%) */
 export function formatGrowthShort(value: number): string {
   const pct = value * 100;
@@ -345,18 +349,3 @@ export function convertCurrency(
     || fromRate <= 0 || baseRate <= 0) return Number.NaN;
   return (value * fromRate) / baseRate;
 }
-
-/** Format a date/timestamp as relative time (e.g., "5m ago", "2h ago") */
-export function formatTimeAgo(date: Date | string): string {
-  const ts = toTimestampMillis(date);
-  if (Number.isNaN(ts)) return "unknown";
-  const seconds = Math.floor((Date.now() - ts) / 1000);
-  if (seconds < 60) return "just now";
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  if (days < 7) return `${days}d ago`;
-  return new Date(ts).toLocaleDateString("en-US", { month: "numeric", day: "numeric", year: "2-digit" });
-}

package/src/utils/futures-generic.ts

@@ -0,0 +1,159 @@
+/**
+ * Generic futures tickers (CL1, TY2F5R): a rolling series that follows the
+ * nth listed contract of a root, not a tradeable contract. Gloom Cloud builds
+ * them; the grammar mirrors its parser. After the root and position, F5 rolls
+ * five business days before first notice (last trade for cash-settled roots),
+ * D15 on the 15th, and without either the generic follows open interest. R
+ * ratio-adjusts, A difference-adjusts, neither leaves prices as traded.
+ */
+
+import { parsePublicTickerKey } from "./exchanges";
+
+export type FuturesGenericRoll =
+  | { rule: "open-interest" }
+  | { rule: "first-notice"; days: number }
+  | { rule: "fixed-day"; day: number };
+
+export type FuturesGenericAdjust = "none" | "ratio" | "difference";
+
+export interface FuturesGeneric {
+  ticker: string;
+  /** The root as typed, which may be a Bloomberg alias (TY for ZN). */
+  prefix: string;
+  root: string;
+  position: number;
+  roll: FuturesGenericRoll;
+  adjust: FuturesGenericAdjust;
+}
+
+/** Roots Gloom Cloud archives daily, by the venue that lists them. */
+const ROOT_VENUES: Readonly<Record<string, string>> = Object.fromEntries(([
+  ["CME", ["ES", "NQ", "RTY", "6E", "6J", "6B", "6A", "6C", "6S", "SR3", "LE", "GF", "HE", "LBR", "DC", "CSC", "GD", "BTC", "ETH", "SOL", "XRP"]],
+  ["CBT", ["YM", "ZT", "ZF", "ZN", "ZB", "UB", "ZQ", "ZC", "ZS", "ZW", "ZM", "ZL", "KE", "ZO", "ZR"]],
+  ["NYM", ["CL", "BZ", "NG", "RB", "HO", "PL", "PA", "B0", "TTF"]],
+  ["CMX", ["GC", "SI", "HG", "ALI", "HRC", "UX"]],
+  ["NYB", ["KC", "SB", "CC", "CT", "OJ"]],
+  ["CFE", ["VX"]],
+] as const).flatMap(([venue, roots]) => roots.map((root) => [root, venue])));
+
+/** Other names quotes give each venue, which a listing may carry as its exchange. */
+const VENUE_NAMES: Readonly<Record<string, readonly string[]>> = {
+  NYM: ["NYMEX", "NY MERCANTILE"], CBT: ["CBOT"], CMX: ["COMEX"], NYB: ["ICE FUTURES", "NYBOT"], CFE: ["CBOE FUTURES"],
+};
+
+/** Bloomberg's codes where they differ from the exchange's. */
+const ALIASES: Readonly<Record<string, string>> = {
+  TY: "ZN", US: "ZB", FV: "ZF", TU: "ZT", WN: "UB", DM: "YM", FF: "ZQ", SFR: "SR3",
+  CO: "BZ", XB: "RB", LC: "LE", LH: "HE", FC: "GF", SM: "ZM", BO: "ZL", KW: "KE",
+};
+
+/** Roots whose contracts give first notice before last trade; the rest roll against last trade. */
+const FIRST_NOTICE_ROOTS = new Set([
+  "ZC", "ZS", "ZW", "ZM", "ZL", "KE", "ZO", "ZR", "GC", "SI", "HG", "PL", "PA", "ALI", "ZT", "ZF", "ZN", "ZB", "UB", "KC", "CC", "CT", "LE",
+]);
+
+export function parseFuturesGeneric(value: unknown): FuturesGeneric | null {
+  if (typeof value !== "string") return null;
+  const ticker = value.trim().toUpperCase();
+  if (!/^[A-Z0-9]{2,12}$/.test(ticker)) return null;
+  for (let length = Math.min(4, ticker.length - 1); length >= 1; length -= 1) {
+    const prefix = ticker.slice(0, length);
+    const root = ALIASES[prefix] ?? prefix;
+    if (!ROOT_VENUES[root]) continue;
+    const match = /^(\d{1,2})(?:([FD])(\d{1,2}))?([RA])?$/.exec(ticker.slice(length));
+    if (!match) continue;
+    const position = Number(match[1]);
+    if (match[1]!.startsWith("0") || position < 1 || position > 24) return null;
+    const amount = match[3] == null ? 0 : Number(match[3]);
+    const roll: FuturesGenericRoll = match[2] === "F" ? { rule: "first-notice", days: amount }
+      : match[2] === "D" ? { rule: "fixed-day", day: amount } : { rule: "open-interest" };
+    if (roll.rule === "first-notice" && roll.days > 30) return null;
+    if (roll.rule === "fixed-day" && (roll.day < 1 || roll.day > 28)) return null;
+    return { ticker, prefix, root, position, roll, adjust: match[4] === "R" ? "ratio" : match[4] === "A" ? "difference" : "none" };
+  }
+  return null;
+}
+
+/**
+ * A listing that is a generic: the symbol parses and its exchange is empty or
+ * the root's own venue, as Gloom Cloud decides, so a security elsewhere that
+ * happens to spell like one (PL8 on the ASX) is never captioned or rolled as one.
+ */
+export function futuresGenericListing(symbol: string, exchange?: string | null): FuturesGeneric | null {
+  const key = parsePublicTickerKey(symbol);
+  const generic = parseFuturesGeneric(key.symbol);
+  if (!generic) return null;
+  const venue = (key.exchange || exchange || "").trim().toUpperCase();
+  const own = ROOT_VENUES[generic.root]!;
+  return !venue || venue === own || VENUE_NAMES[own]?.includes(venue) ? generic : null;
+}
+
+/**
+ * Whether two listings are the same generic under any roll rule or adjustment
+ * (CL1 and CL1F5R, TY1 and ZN1). The chart's Roll and Adjust controls rewrite
+ * the ticker, and what it follows must not rewrite it back.
+ */
+export function isSameFuturesGeneric(
+  a: { symbol: string; exchange?: string | null },
+  b: { symbol: string; exchange?: string | null },
+): boolean {
+  const left = futuresGenericListing(a.symbol, a.exchange);
+  const right = futuresGenericListing(b.symbol, b.exchange);
+  return !!left && !!right && left.root === right.root && left.position === right.position;
+}
+
+export function formatFuturesGeneric(generic: Pick<FuturesGeneric, "prefix" | "position" | "roll" | "adjust">): string {
+  const { roll, adjust } = generic;
+  const rollCode = roll.rule === "first-notice" ? `F${roll.days}` : roll.rule === "fixed-day" ? `D${roll.day}` : "";
+  return `${generic.prefix}${generic.position}${rollCode}${adjust === "ratio" ? "R" : adjust === "difference" ? "A" : ""}`;
+}
+
+export function futuresGenericOrdinal(position: number): string {
+  const tens = position % 100;
+  return `${position}${tens >= 11 && tens <= 13 ? "th" : ["th", "st", "nd", "rd"][position % 10] ?? "th"}`;
+}
+
+/**
+ * How a generic's price reads: index and VIX futures in points (not dollars),
+ * Treasury futures in 32nds of par; everything else in its quote currency.
+ */
+export function futuresGenericPriceBasis(generic: Pick<FuturesGeneric, "root">): "points" | "thirty-seconds" | null {
+  if (["ES", "NQ", "RTY", "YM", "GD", "VX"].includes(generic.root)) return "points";
+  if (["ZT", "ZF", "ZN", "ZB", "UB"].includes(generic.root)) return "thirty-seconds";
+  return null;
+}
+
+/** Whether a root's date rules count back from first notice or from last trade. */
+export function futuresGenericNotice(root: string): "first notice" | "last trade" {
+  return FIRST_NOTICE_ROOTS.has(root) ? "first notice" : "last trade";
+}
+
+export function futuresGenericRollLabel(generic: Pick<FuturesGeneric, "root" | "roll">): string {
+  const { roll } = generic;
+  if (roll.rule === "open-interest") return "open interest switch";
+  if (roll.rule === "fixed-day") return `fixed day ${roll.day}`;
+  const notice = futuresGenericNotice(generic.root);
+  if (roll.days === 0) return notice === "first notice" ? "on first notice" : "after last trade";
+  return `${roll.days} ${roll.days === 1 ? "day" : "days"} before ${notice}`;
+}
+
+export function futuresGenericAdjustLabel(adjust: FuturesGenericAdjust): string {
+  return adjust === "ratio" ? "ratio adjusted" : adjust === "difference" ? "difference adjusted" : "unadjusted";
+}
+
+/** The legend caption: says it is a generic and how it rolls, so it is never read as one contract. */
+export function futuresGenericCaption(generic: FuturesGeneric): string {
+  return `${generic.ticker} ${futuresGenericOrdinal(generic.position)} generic · ${futuresGenericRollLabel(generic)} · ${futuresGenericAdjustLabel(generic.adjust)}`;
+}
+
+/** Choice values for the chart's roll control: the three rules at their usual settings. */
+export function futuresGenericRollValue(roll: FuturesGenericRoll): string {
+  return roll.rule === "first-notice" ? `f${roll.days}` : roll.rule === "fixed-day" ? `d${roll.day}` : "oi";
+}
+
+export function futuresGenericRollFromValue(value: string): FuturesGenericRoll | null {
+  if (value === "oi") return { rule: "open-interest" };
+  const match = /^([fd])(\d{1,2})$/.exec(value);
+  if (!match) return null;
+  return match[1] === "f" ? { rule: "first-notice", days: Number(match[2]) } : { rule: "fixed-day", day: Number(match[2]) };
+}

package/src/utils/guards.ts

@@ -0,0 +1,37 @@
+// Narrowing helpers for unknown payloads: decoded JSON, persisted state, RPC
+// messages and anything else that crosses a trust boundary.
+
+/** A plain object: not null and not an array. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** The value as a plain object, or null when it is not one. */
+export function recordOrNull(value: unknown): Record<string, unknown> | null {
+  return isRecord(value) ? value : null;
+}
+
+/** The value as a plain object, or an empty one, so nested reads can chain. */
+export function asRecord(value: unknown): Record<string, unknown> {
+  return isRecord(value) ? value : {};
+}
+
+/** A number that is not NaN or infinite. */
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** The value when it is a finite number, otherwise null. */
+export function finiteOrNull(value: unknown): number | null {
+  return isFiniteNumber(value) ? value : null;
+}
+
+/** An array holding only strings. */
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+/** A string that parses as a date. */
+export function isDateString(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}

package/src/utils/hash.ts

@@ -1,8 +1,23 @@
-export function fnv1aHashString(input: string): string {
+/** 32-bit FNV-1a over UTF-16 code units, as eight lowercase hex digits. */
+export function fnv1aHex(input: string): string {
   let hash = 0x811c9dc5;
   for (let index = 0; index < input.length; index += 1) {
     hash ^= input.charCodeAt(index);
     hash = Math.imul(hash, 0x01000193);
   }
-  return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function fnv1aHashString(input: string): string {
+  return `fnv1a:${fnv1aHex(input)}`;
+}
+
+/** JSON with object keys sorted at every depth, so equal values hash equally. */
+export function stableStringify(value: unknown): string {
+  if (value == null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object).sort().map((key) => (
+    `${JSON.stringify(key)}:${stableStringify(object[key])}`
+  )).join(",")}}`;
 }

package/src/utils/http-proxy-response.ts

@@ -1,13 +1,31 @@
 /**
- * Rebuilds a `Response` from a proxied envelope.
+ * The envelope a proxied plugin request travels in.
  *
- * Both proxying transports (desktop's Bun backend, the web app's worker route)
- * return `set-cookie` alongside the other headers rather than inside them,
+ * A renderer that cannot reach a third-party API itself (the desktop webview,
+ * the hosted web app, the pane screenshot page) posts the request to a process
+ * that can: the desktop's Bun backend, the web app's worker route, or the CLI
+ * that serves the screenshot page. Every hop uses these shapes and helpers, so
+ * the client half of each transport behaves identically.
+ *
+ * `set-cookie` travels beside the other headers rather than inside them,
  * because a `Headers` object built in a renderer cannot hold multiple cookies
  * and the browser strips the header anyway. Callers that read cookies, like a
  * plugin completing a login, need `get("set-cookie")` and `getSetCookie()` to
- * work, so those are restored here.
+ * work, so `createProxyResponse` restores them.
  */
+export interface HttpProxyRequestInit {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  redirect?: "follow" | "error" | "manual";
+  timeoutMs?: number;
+}
+
+export interface HttpProxyRequestEnvelope {
+  url: string;
+  init?: HttpProxyRequestInit;
+}
+
 export interface HttpProxyResponseEnvelope {
   status: number;
   statusText: string;
@@ -16,6 +34,105 @@ export interface HttpProxyResponseEnvelope {
   body: string;
 }
 
+function headersToRecord(headers: HeadersInit | undefined): Record<string, string> {
+  const record: Record<string, string> = {};
+  if (!headers) return record;
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      record[key] = value;
+    });
+    return record;
+  }
+  if (Array.isArray(headers)) {
+    for (const [key, value] of headers) record[key] = value;
+    return record;
+  }
+  return { ...headers };
+}
+
+async function serializeBody(body: BodyInit | null | undefined): Promise<string | undefined> {
+  if (body == null) return undefined;
+  if (typeof body === "string") return body;
+  return new Response(body).text();
+}
+
+/** Client half: flattens a `fetch` call into JSON the proxy can carry. */
+export async function toRequestEnvelope(
+  url: string,
+  init?: RequestInit,
+  timeoutMs?: number,
+): Promise<HttpProxyRequestEnvelope> {
+  return {
+    url,
+    init: {
+      method: init?.method,
+      headers: headersToRecord(init?.headers),
+      body: await serializeBody(init?.body),
+      redirect: init?.redirect,
+      timeoutMs,
+    },
+  };
+}
+
+/** The request options a proxy may trust, whatever the envelope held. */
+export interface ProxiedRequestInit {
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  redirect?: "follow" | "error" | "manual";
+  /** Positive and finite when present; each proxy applies its own ceiling. */
+  timeoutMs?: number;
+}
+
+/** Server half: reads an envelope's `init` without trusting its shape. */
+export function readRequestInit(raw: unknown): ProxiedRequestInit {
+  const init = raw && typeof raw === "object" && !Array.isArray(raw)
+    ? raw as Record<string, unknown>
+    : {};
+  const method = typeof init.method === "string" && init.method.trim()
+    ? init.method.trim().toUpperCase()
+    : "GET";
+  const headers = init.headers && typeof init.headers === "object" && !Array.isArray(init.headers)
+    ? Object.fromEntries(
+      Object.entries(init.headers as Record<string, unknown>)
+        .filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+    )
+    : {};
+  return {
+    method,
+    headers,
+    body: typeof init.body === "string" && method !== "GET" && method !== "HEAD" ? init.body : undefined,
+    redirect: init.redirect === "manual" || init.redirect === "error" || init.redirect === "follow"
+      ? init.redirect
+      : undefined,
+    timeoutMs: typeof init.timeoutMs === "number" && Number.isFinite(init.timeoutMs) && init.timeoutMs > 0
+      ? init.timeoutMs
+      : undefined,
+  };
+}
+
+/**
+ * Server half: the response head as JSON. `set-cookie` is left out of
+ * `headers` and listed in `setCookie`, so a web proxy never emits a third
+ * party's cookie on its own origin.
+ */
+export function toResponseHead(response: Response): Omit<HttpProxyResponseEnvelope, "body"> & { setCookie: string[] } {
+  const headers: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === "set-cookie") return;
+    headers[key] = value;
+  });
+  const setCookie = [...(response.headers.getSetCookie?.() ?? [])];
+  const singleSetCookie = response.headers.get("set-cookie");
+  if (setCookie.length === 0 && singleSetCookie) setCookie.push(singleSetCookie);
+  return { status: response.status, statusText: response.statusText, headers, setCookie };
+}
+
+/** Server half: the whole response as JSON, body buffered. */
+export async function toResponseEnvelope(response: Response): Promise<HttpProxyResponseEnvelope & { setCookie: string[] }> {
+  return { ...toResponseHead(response), body: await response.text() };
+}
+
 export function createProxyResponseHeaders(
   headers: Record<string, string>,
   setCookie: string[] = [],
@@ -31,6 +148,7 @@ export function createProxyResponseHeaders(
   return responseHeaders;
 }
 
+/** Client half: rebuilds a `Response` from a proxied envelope. */
 export function createProxyResponse(envelope: HttpProxyResponseEnvelope): Response {
   const headers = createProxyResponseHeaders(envelope.headers, envelope.setCookie ?? []);
   const response = new Response(envelope.body, {

package/src/utils/math.ts

@@ -0,0 +1,12 @@
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * An index kept inside a list of `length` items. An empty list has no valid
+ * index, so it returns `empty`: 0 by default, or -1 where callers need to tell
+ * "nothing selected" apart from the first row.
+ */
+export function clampIndex(index: number, length: number, empty = 0): number {
+  return length <= 0 ? empty : clamp(index, 0, length - 1);
+}

package/src/utils/platform.ts

@@ -0,0 +1,34 @@
+export type DesktopPlatform = "darwin" | "win32" | "linux" | "unknown";
+
+type NavigatorLike = {
+  platform?: string;
+  userAgent?: string;
+  userAgentData?: { platform?: string };
+};
+
+// "darwin" contains "win", so macOS is matched first.
+function classifyPlatform(raw: string | undefined): Exclude<DesktopPlatform, "unknown"> | null {
+  if (!raw) return null;
+  if (/(darwin|mac|iphone|ipad|ipod)/i.test(raw)) return "darwin";
+  if (/win/i.test(raw)) return "win32";
+  if (/(linux|x11|android|\bcros\b|bsd|\baix\b|sunos)/i.test(raw)) return "linux";
+  return null;
+}
+
+function navigatorPlatform(): string {
+  const navigatorLike = (globalThis as { navigator?: NavigatorLike }).navigator;
+  return [
+    navigatorLike?.userAgentData?.platform,
+    navigatorLike?.platform,
+    navigatorLike?.userAgent,
+  ].filter(Boolean).join(" ");
+}
+
+/**
+ * The OS the UI runs on. A `hint` that names an OS, such as the desktop host's
+ * `process.platform`, wins. Anything else, including the web build's
+ * `"browser"` sentinel, falls back to sniffing the navigator.
+ */
+export function detectPlatform(hint?: string): DesktopPlatform {
+  return classifyPlatform(hint?.trim()) ?? classifyPlatform(navigatorPlatform()) ?? "unknown";
+}

package/src/utils/plugin-proxy-hosts.json

@@ -10,7 +10,6 @@
     "nasdaqtrader.com",
     "production.dataviz.cnn.io",
     "query1.finance.yahoo.com",
-    "query2.finance.yahoo.com",
-    "stockanalysis.com"
+    "query2.finance.yahoo.com"
   ]
 }

package/src/utils/plugin-proxy-hosts.ts

@@ -18,6 +18,9 @@ import allowed from "./plugin-proxy-hosts.json";
  */
 export const PROXY_ALLOWED_HOSTS: readonly string[] = allowed.hosts;
 
+/** The worker route the browser posts proxied requests to. */
+export const HTTP_PROXY_PATH = "/http-proxy";
+
 /** Matches a host exactly, or as a subdomain of an allowed parent. */
 export function isProxiedHost(hostname: string, hosts: readonly string[] = PROXY_ALLOWED_HOSTS): boolean {
   const host = hostname.toLowerCase();

package/src/utils/price-history-integrity.ts

@@ -1,4 +1,5 @@
 import type { PricePoint } from "../types/financials";
+import { isFiniteNumber } from "./guards";
 
 type ReportedPricePoint = Readonly<Omit<PricePoint, "date" | "historySource"> & {
   date: string;
@@ -22,10 +23,6 @@ export function mergePriceHistoryIntegrity(...entries: readonly PriceHistoryInte
   });
 }
 
-function finite(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
 function above(left: number, right: number): boolean {
   return left - right > 8 * Number.EPSILON * Math.max(Math.abs(left), Math.abs(right));
 }
@@ -33,9 +30,9 @@ function above(left: number, right: number): boolean {
 /** Missing OHLC fields are not contradictory: close-only histories remain usable. */
 export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity | undefined {
   const { open, high, low, close } = point;
-  const invalid = (finite(high) && finite(low) && above(low, high))
-    || [open, close].some((value) => finite(value)
-      && ((finite(high) && above(value, high)) || (finite(low) && above(low, value))));
+  const invalid = (isFiniteNumber(high) && isFiniteNumber(low) && above(low, high))
+    || [open, close].some((value) => isFiniteNumber(value)
+      && ((isFiniteNumber(high) && above(value, high)) || (isFiniteNumber(low) && above(low, value))));
   if (!invalid) return undefined;
   const date = new Date(point.date);
   return Object.freeze({
@@ -46,7 +43,7 @@ export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity |
 
 /** Calculation/display fields deliberately exclude the contradictory source row. */
 export function pricePointValues(point: PricePoint, integrity = pricePointIntegrity(point)) {
-  const value = (number: number | undefined) => !integrity && finite(number) ? number : null;
+  const value = (number: number | undefined) => !integrity && isFiniteNumber(number) ? number : null;
   return {
     open: value(point.open), high: value(point.high), low: value(point.low),
     close: value(point.close), volume: value(point.volume),