gloomberb 0.13.2 → 0.14.0

package/src/types/broker.ts

@@ -3,7 +3,7 @@ import type { TimeRange } from "../time-series/range";
 import type { ChartResolutionSupport, ManualChartResolution } from "../time-series/resolution";
 import type { BrokerInstanceConfig } from "./config";
 import type { QuoteSubscriptionTarget } from "./data-provider";
-import type { BrokerContractRef, InstrumentSearchResult } from "./instrument";
+import type { BrokerContractRef, InstrumentSearchResult, PriceBasis } from "./instrument";
 import type {
   BrokerAccount,
   BrokerExecution,
@@ -19,6 +19,7 @@ export interface BrokerPosition {
   exchange: string;
   shares: number;
   avgCost?: number;
+  priceBasis?: PriceBasis;
   currency: string;
   dateAcquired?: string;
   /** Optional account/portfolio identifier from the broker */

package/src/types/config.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   createPaneInstance,
+  findPaneInstance,
   findPrimaryPaneInstance,
   materializeDetachedPanesAsFloating,
   resolveFollowBindingInstance,
@@ -18,6 +19,36 @@ function createLayout(instances: PaneInstanceConfig[]): LayoutConfig {
   };
 }
 
+describe("findPaneInstance", () => {
+  // The lookup caches an index per instances array. In-place edits, which the
+  // screenshot CLI and chart settings still do, must not serve stale hits.
+  test("survives in-place replacement and removal in the same array", () => {
+    const first = createPaneInstance("ticker-detail", { instanceId: "ticker-detail:a" });
+    const second = createPaneInstance("ticker-detail", { instanceId: "ticker-detail:b" });
+    const layout = createLayout([first, second]);
+
+    expect(findPaneInstance(layout, "ticker-detail:b")).toBe(second);
+
+    const replacement = createPaneInstance("ticker-detail", { instanceId: "ticker-detail:c" });
+    layout.instances[1] = replacement;
+    expect(findPaneInstance(layout, "ticker-detail:b")).toBeUndefined();
+    expect(findPaneInstance(layout, "ticker-detail:c")).toBe(replacement);
+
+    layout.instances.splice(0, 1);
+    expect(findPaneInstance(layout, "ticker-detail:a")).toBeUndefined();
+    expect(findPaneInstance(layout, "ticker-detail:c")).toBe(replacement);
+
+    layout.instances.push(first);
+    expect(findPaneInstance(layout, "ticker-detail:a")).toBe(first);
+  });
+
+  test("returns the first instance when an id is duplicated", () => {
+    const first = createPaneInstance("chat", { instanceId: "chat:main" });
+    const duplicate = createPaneInstance("chat", { instanceId: "chat:main" });
+    expect(findPaneInstance(createLayout([first, duplicate]), "chat:main")).toBe(first);
+  });
+});
+
 describe("findPrimaryPaneInstance", () => {
   test("prefers the main non-fixed ticker pane", () => {
     const layout = createLayout([

package/src/types/config.ts

@@ -1,4 +1,5 @@
 import type { Portfolio, Watchlist } from "./ticker";
+import type { BrokerContractRef, TickerListingRef } from "./instrument";
 import type { LanguagePreference } from "../i18n/languages";
 
 export const CURRENT_CONFIG_VERSION = 22;
@@ -29,7 +30,7 @@ export interface ColumnConfig {
 
 export type PaneBinding =
   | { kind: "none" }
-  | { kind: "fixed"; symbol: string }
+  | { kind: "fixed"; symbol: string; instrument?: BrokerContractRef | null; listing?: TickerListingRef }
   | { kind: "follow"; sourceInstanceId: string };
 
 export interface DockedPlacementMemory {
@@ -66,6 +67,8 @@ export interface PaneInstanceConfig {
   params?: Record<string, string>;
   settings?: Record<string, unknown>;
   placementMemory?: PanePlacementMemory;
+  /** Pinned by the user: the keyboard close shortcuts leave this pane alone. */
+  locked?: boolean;
 }
 
 interface DockPaneNode {
@@ -107,6 +110,22 @@ export interface LayoutConfig {
   detached: DetachedPaneEntry[];
 }
 
+/**
+ * Where a tab's content came from when it is linked to a team layout. The
+ * revision and fingerprint say whether the local copy drifted and whether the
+ * team has something newer; the arrangement on screen is never part of it.
+ */
+export interface LayoutOrigin {
+  kind: "team";
+  teamId: string;
+  layoutId: string;
+  /** The team revision this tab last matched. */
+  revision: number;
+  /** Fingerprint of the content at `revision`, so edits can be detected offline. */
+  contentHash: string;
+  syncedAt: string;
+}
+
 export interface SavedLayout {
   id?: string;
   name: string;
@@ -114,6 +133,7 @@ export interface SavedLayout {
   paneState?: Record<string, Record<string, unknown>>;
   focusedPaneId?: string | null;
   activePanel?: "left" | "right";
+  origin?: LayoutOrigin;
 }
 
 export type OnboardingStage =
@@ -318,11 +338,6 @@ const DEFAULT_MACRO_LAYOUT: LayoutConfig = {
       binding: { kind: "none" },
       settings: { stat: "cpi-yoy", range: "20Y" },
     },
-    {
-      instanceId: "fear-greed:macro",
-      paneId: "fear-greed",
-      binding: { kind: "none" },
-    },
     {
       instanceId: "volatility-term-structure:macro",
       paneId: "volatility-term-structure",
@@ -348,7 +363,7 @@ const DEFAULT_MONITOR_LAYOUT: LayoutConfig = {
       axis: "horizontal",
       ratio: 0.42,
       first: { kind: "pane", instanceId: "news-top:main" },
-      second: { kind: "pane", instanceId: "prediction-markets:main" },
+      second: { kind: "pane", instanceId: "market-movers:main" },
     },
     second: {
       kind: "split",
@@ -365,8 +380,8 @@ const DEFAULT_MONITOR_LAYOUT: LayoutConfig = {
       binding: { kind: "none" },
     },
     {
-      instanceId: "prediction-markets:main",
-      paneId: "prediction-markets",
+      instanceId: "market-movers:main",
+      paneId: "market-movers",
       binding: { kind: "none" },
     },
     {
@@ -563,6 +578,7 @@ export function createPaneInstance(
     params: options.params ? { ...options.params } : undefined,
     settings: clonePaneSettings(options.settings),
     placementMemory: clonePlacementMemory(options.placementMemory),
+    locked: options.locked === true ? true : undefined,
   };
 }
 
@@ -756,8 +772,31 @@ export function createBlankLayout(): LayoutConfig {
   return cloneLayout(BLANK_LAYOUT);
 }
 
+// Every pane hook selects its instance on every store update, so a linear
+// scan multiplies by subscriber count times dispatch rate. Layout updates
+// replace the instances array, which keys the index; the entry is verified on
+// read so an in-place edit can only cost a rebuild, never a stale hit.
+const paneInstanceIndexes = new WeakMap<readonly PaneInstanceConfig[], Map<string, number>>();
+
+function buildPaneInstanceIndex(instances: readonly PaneInstanceConfig[]): Map<string, number> {
+  const index = new Map<string, number>();
+  instances.forEach((instance, position) => {
+    if (!index.has(instance.instanceId)) index.set(instance.instanceId, position);
+  });
+  paneInstanceIndexes.set(instances, index);
+  return index;
+}
+
 export function findPaneInstance(layout: LayoutConfig, instanceId: string): PaneInstanceConfig | undefined {
-  return layout.instances.find((instance) => instance.instanceId === instanceId);
+  const instances = layout.instances;
+  let index = paneInstanceIndexes.get(instances) ?? buildPaneInstanceIndex(instances);
+  let position = index.get(instanceId);
+  let candidate = position === undefined ? undefined : instances[position];
+  if (candidate?.instanceId === instanceId) return candidate;
+  index = buildPaneInstanceIndex(instances);
+  position = index.get(instanceId);
+  candidate = position === undefined ? undefined : instances[position];
+  return candidate?.instanceId === instanceId ? candidate : undefined;
 }
 
 export function createDefaultConfig(dataDir: string): AppConfig {

package/src/types/data-provider.ts

@@ -1,7 +1,9 @@
+import type { ExchangeRateSnapshot } from "./exchange-rate";
 import type {
   AnalystResearchData,
   CorporateActionsData,
   Quote,
+  QuoteMetadata,
   TickerFinancials,
   PricePoint,
   OptionsChain,
@@ -11,6 +13,12 @@ import type { TimeRange } from "../time-series/range";
 import type { ChartResolutionSupport, ManualChartResolution } from "../time-series/resolution";
 import type { BrokerContractRef, InstrumentSearchResult } from "./instrument";
 import type { CachePolicyMap } from "./persistence";
+import type { CachedQueryHandle } from "../data/cached-query";
+
+export type CachedAssetMethod = "getExchangeRate" | "getHolders" | "getAnalystResearch" | "getCorporateActions"
+  | "getOptionsChain" | "getSecFilings" | "getSecFilingDocuments" | "getSecFilingContent" | "getArticleSummary";
+export type CachedAssetArgs<K extends CachedAssetMethod> = Parameters<NonNullable<AssetDataProvider[K]>>;
+export type CachedAssetValue<K extends CachedAssetMethod> = Awaited<ReturnType<NonNullable<AssetDataProvider[K]>>>;
 
 export interface NewsItem {
   title: string;
@@ -25,6 +33,8 @@ export interface SecFilingItem {
   form: string;
   filingDate: Date;
   acceptedAt?: Date;
+  /** Unmodified SEC acceptanceDateTime; a missing timezone is not inferred. */
+  acceptedAtRaw?: string;
   primaryDocument?: string;
   primaryDocDescription?: string;
   items?: string;
@@ -44,12 +54,31 @@ export interface SecFilingDocument {
   isPrimary: boolean;
 }
 
+export type EarningsEstimateField =
+  | "epsEstimate" | "epsLow" | "epsHigh" | "epsYearAgo" | "epsGrowth" | "epsAnalysts"
+  | "epsTrend7dAgo" | "epsTrend30dAgo"
+  | "epsRevisionUp7d" | "epsRevisionUp30d" | "epsRevisionDown7d" | "epsRevisionDown30d"
+  | "revenueEstimate" | "revenueLow" | "revenueHigh" | "revenueYearAgo" | "revenueGrowth" | "revenueAnalysts";
+
+export interface EarningsEstimateBasis {
+  source: "earningsTrend" | "calendarEvents";
+  /** Selected provider number before any explicit minor-unit normalization. */
+  sourceValue: number;
+  /** Provider forecast label, not a derived fiscal quarter or announcement date. */
+  period: string | null;
+  periodEndDate: string | null;
+  /** Explicit currency for monetary values only; ratios/counts have none. */
+  currency?: string | null;
+  sourceCurrency?: string | null;
+}
+
 export interface EarningsEvent {
   symbol: string;
   name: string;
   earningsDate: Date;
   earningsCallDate?: Date | null;
   isDateEstimate?: boolean | null;
+  estimateBasis?: Partial<Record<EarningsEstimateField, EarningsEstimateBasis>>;
   epsEstimate: number | null;
   epsLow?: number | null;
   epsHigh?: number | null;
@@ -79,9 +108,11 @@ export interface MarketDataRequestContext {
   brokerInstanceId?: string;
   instrument?: BrokerContractRef | null;
   cacheMode?: "default" | "refresh";
+  statementHistory?: "extended";
 }
 
 export interface CachedFinancialsTarget {
+  statementHistory?: "extended";
   symbol: string;
   exchange?: string;
   brokerId?: string;
@@ -135,13 +166,25 @@ export interface AssetDataProvider {
   readonly priority?: number;
   readonly cachePolicy?: CachePolicyMap;
 
+  /** Optional shared query owner. Consumers observe its age and refreshes instead of caching its values again. */
+  getCachedQuery?<K extends CachedAssetMethod>(method: K, args: CachedAssetArgs<K>): CachedQueryHandle<CachedAssetValue<K>>;
+
   canProvide?(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<boolean> | boolean;
+  /**
+   * Name of the source a plain market request reaches first. A router answers
+   * for its highest-priority member; a remote transport asks the process that
+   * owns the router. Absent on a plain provider, whose own name is the answer.
+   */
+  primaryMarketSourceName?(): string | null | Promise<string | null>;
   getCachedFinancialsForTargets?(targets: CachedFinancialsTarget[], options?: { allowExpired?: boolean; includeStaleQuotes?: boolean }): Map<string, TickerFinancials> | Promise<Map<string, TickerFinancials>>;
   getQuotesBatch?(targets: QuoteSubscriptionTarget[], options?: { forceRefresh?: boolean }): Promise<QuoteBatchResult[]>;
   getTickerFinancialsBatch?(targets: CachedFinancialsTarget[], options?: { forceRefresh?: boolean }): Promise<TickerFinancialsBatchResult[]>;
   getTickerFinancials(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<TickerFinancials>;
   getQuote(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<Quote>;
+  /** Listing facts may outlive the quote price; this method never returns price/session values. */
+  getQuoteMetadata?(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<QuoteMetadata | null>;
   getExchangeRate(fromCurrency: string): Promise<number>;
+  getExchangeRateSnapshot?(fromCurrency: string): Promise<ExchangeRateSnapshot>;
   search(query: string, context?: SearchRequestContext): Promise<InstrumentSearchResult[]>;
   getSecFilings?(ticker: string, count?: number, exchange?: string, context?: MarketDataRequestContext): Promise<SecFilingItem[]>;
   getHolders?(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<HolderData>;

package/src/types/exchange-rate.ts

@@ -0,0 +1,13 @@
+/** Quote currency units per one base-currency unit; conversion rates use USD. */
+export interface ExchangeRateSnapshot {
+  fromCurrency: string;
+  toCurrency: "USD";
+  rate: number;
+  source: string;
+  /** Provider observation time, independent of retrieval/cache age. */
+  asOf?: string;
+  fetchedAt: string;
+  staleAt?: string;
+  stale: boolean;
+  delayMinutes?: number;
+}

package/src/types/financials.ts

@@ -1,3 +1,4 @@
+import type { PriceBasis } from "./instrument";
 
 export type MarketState = "PRE" | "REGULAR" | "POST" | "PREPRE" | "POSTPOST" | "CLOSED";
 export type SessionConfidence = "explicit" | "derived" | "unknown";
@@ -19,14 +20,42 @@ export interface QuoteProvenance {
   rejectedPriceProviders?: string[];
 }
 
+/** Static listing facts from a quote observation, without an investable price. */
+export interface QuoteMetadataSource {
+  providerId?: string;
+  lastUpdated?: number;
+  stale?: boolean;
+  provenance?: QuoteProvenance;
+}
+
+export interface QuoteMetadata {
+  symbol: string;
+  currency?: string;
+  instrumentType?: string;
+  listingExchangeName?: string;
+  source: QuoteMetadataSource;
+  /** Overrides only when a missing field was supplied by another observation. */
+  fieldSources?: Partial<Record<"currency" | "instrumentType", QuoteMetadataSource>>;
+}
+
 export interface Quote {
+  /** Applies to this price observation; a stored position cannot supply it. */
+  priceBasis?: PriceBasis;
   symbol: string;
+  /** Provider-reported security type, independent of the company profile. */
+  instrumentType?: string;
   providerId?: string;
   price: number;
   currency: string;
   change: number;
   changePercent: number;
   previousClose?: number;
+  /** Official close of a completed regular session, in this quote's currency. */
+  regularClose?: number;
+  /** Exchange-local date of regularClose; separate from the daily previous-close reference. */
+  regularCloseSessionDate?: string;
+  /** Provider's exchange-local session date for the daily quote reference. */
+  changeSessionDate?: string;
   high52w?: number;
   low52w?: number;
   marketCap?: number;
@@ -58,6 +87,10 @@ export interface Quote {
   high?: number;
   low?: number;
   mark?: number;
+  /** Executed trade, separate from a midpoint or indicative mark. */
+  lastTradePrice?: number;
+  /** Timestamp of that trade in milliseconds. */
+  lastTradeTime?: number;
   provenance?: QuoteProvenance;
   /** Freshness class for the quote data. Provider identity lives in providerId/provenance. */
   dataSource?: QuoteDataSource;
@@ -70,13 +103,26 @@ export interface QuoteContribution extends Quote {
 export type QuoteContributionMap = Record<string, QuoteContribution>;
 
 export interface Fundamentals {
+  source?: "twelvedata" | "yahoo";
+  fetchedAt?: string;
+  stale?: boolean;
+  /** Currency of reported revenue, income, and cash flows; may differ from the listing. */
+  financialCurrency?: string;
+  /** Provider-reported issuer market cap; marketCapCurrency identifies its units when known. */
+  marketCap?: number;
+  marketCapCurrency?: string;
   trailingPE?: number;
   forwardPE?: number;
   pegRatio?: number;
   enterpriseValue?: number;
+  enterpriseToRevenue?: number;
+  /** Explicit provider retractions; omitted fields alone remain eligible for fallback. */
+  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue">;
   operatingCashFlow?: number;
   freeCashFlow?: number;
   dividendYield?: number;
+  dividendYieldBasis?: "forward" | "trailing";
+  dividendYieldSource?: "twelvedata" | "yahoo";
   revenue?: number;
   netIncome?: number;
   eps?: number;
@@ -152,6 +198,8 @@ export interface AnalystRatingRecord {
 export interface AnalystEstimateRecord {
   date: string;
   period: string;
+  /** Explicit currency for these estimates; independent of the listing currency. */
+  currency?: string;
   analysts?: number;
   average?: number;
   low?: number;
@@ -162,6 +210,8 @@ export interface AnalystEstimateRecord {
 
 export interface AnalystResearchData {
   providerId?: string;
+  fetchedAt?: string;
+  stale?: boolean;
   symbol: string;
   name?: string;
   currency?: string;
@@ -184,13 +234,18 @@ export interface DividendAction {
 export interface SplitAction {
   date: string;
   description?: string;
+  /** Provider adjustment ratio; may represent a split or a spinoff price adjustment, not verified share terms. */
   ratio?: number;
+  /** Denominator of the provider adjustment factor. */
   fromFactor?: number;
+  /** Numerator of the provider adjustment factor. */
   toFactor?: number;
 }
 
 export interface EarningsAction {
   date: string;
+  dateType?: "announcement" | "fiscal-period-end";
+  currency?: string;
   time?: string;
   epsEstimate?: number;
   epsActual?: number;
@@ -200,6 +255,9 @@ export interface EarningsAction {
 
 export interface CorporateActionsData {
   providerId?: string;
+  fetchedAt?: string;
+  stale?: boolean;
+  coverage?: Partial<Record<"dividends" | "splits" | "earnings", "available" | "unavailable">>;
   symbol: string;
   name?: string;
   currency?: string;
@@ -217,12 +275,45 @@ export interface CompanyProfile {
   industry?: string;
 }
 
+export type IncomeStatementField = "netIncome" | "netIncomeIncludingNoncontrollingInterests" | "netIncomeCommonStockholders";
+
+export interface IncomeStatementSource {
+  source: "sec";
+  concept: string;
+  accessionNumber?: string;
+  filed?: string;
+  startDate?: string;
+  endDate: string;
+  unit: string;
+  basis: "parent" | "consolidated" | "common";
+}
+
 export interface FinancialStatement {
+  /** Unresolved, source-attested observation withdrawals; identifiers are validated on read. */
+  withdrawnObservations?: string[];
+  /** SEC EPS share basis; raw source values remain available in the evidence. */
+  epsBasis?: import("../utils/sec-eps-basis").SecEpsBasis;
   date: string;
+  /** Source of the fiscal period date; does not establish metric publication dates. */
+  dateSource?: "sec" | "provider";
+  /** Original vendor period date when independent filing evidence changes it. */
+  providerDate?: string;
+  /** Filing evidence for the period identity only, not availability of every field. */
+  dateEvidence?: {
+    accessionNumber: string;
+    filed: string;
+    startDate: string;
+  };
+  /** Reporting currency for monetary statement fields (per-share values use reported shares). */
+  currency?: string;
   /** Earliest date on which the complete row was publicly available, when known. */
   availableAt?: string;
   /** Per-field publication dates used by point-in-time charts and calculations. */
   fieldAvailability?: Record<string, string>;
+  /** Income attribution belongs to each field, not to the row's date evidence. */
+  fieldSources?: Partial<Record<IncomeStatementField, IncomeStatementSource>>;
+  /** Explicit source coverage gaps must not be filled by another income basis. */
+  unavailableFields?: IncomeStatementField[];
   // Income Statement
   totalRevenue?: number;
   costOfRevenue?: number;
@@ -244,6 +335,7 @@ export interface FinancialStatement {
   interestExpense?: number;
   taxProvision?: number;
   netIncome?: number;
+  netIncomeIncludingNoncontrollingInterests?: number;
   ebitda?: number;
   basicEps?: number;
   eps?: number; // diluted
@@ -364,7 +456,18 @@ export interface FinancialStatement {
   treasurySharesNumber?: number;
 }
 
+/** Verified provider identity retained with observations through cache/clipping. */
+export interface PriceHistorySource {
+  provider: "yahoo" | "twelvedata";
+  symbol: "SHEL";
+  exchange: "LSE";
+  currency: "GBP";
+  /** Source coverage restriction, not security inception or an adjustment ratio. */
+  verifiedLineageStart?: "2005-07-21";
+}
+
 export interface PricePoint {
+  historySource?: PriceHistorySource;
   date: Date;
   open?: number;
   high?: number;
@@ -373,14 +476,72 @@ export interface PricePoint {
   volume?: number;
 }
 
+export interface StatementHistoryAttempt {
+  mode: "extended";
+  source: "sec";
+  status: "available" | "unsupported" | "retryable-failure";
+  fetchedAt: string;
+  attemptedAt?: string;
+  cik?: string;
+  reason?: string;
+}
+
+/** Consensus EPS for one reported quarter as it stood at the report. */
+export interface ReportedEpsEstimate {
+  /** Announcement date. A row without an actual is an upcoming report. */
+  date: string;
+  epsEstimate?: number;
+  epsActual?: number;
+}
+
+export type ConsensusPeriod = "current quarter" | "next quarter" | "current year" | "next year";
+
+/** Today's consensus for a period still open. */
+export interface ConsensusEpsEstimate {
+  period: ConsensusPeriod | string;
+  /** Fiscal period end. */
+  date: string;
+  average?: number;
+  analysts?: number;
+  currency?: string;
+}
+
+/** One day's observation of the consensus for a period, recorded by the cloud. */
+export interface ConsensusEpsSnapshot {
+  observedOn: string;
+  period: ConsensusPeriod | string;
+  periodEnd?: string;
+  epsAverage?: number;
+  analysts?: number;
+  source: string;
+}
+
+/**
+ * The inputs behind a forward multiple history. Providers only serve today's
+ * consensus, so the past is the pre-report consensus per quarter plus whatever
+ * the cloud has recorded day by day since it started observing the listing.
+ */
+export interface EpsEstimateHistory {
+  fetchedAt?: string;
+  currency?: string;
+  reported: ReportedEpsEstimate[];
+  consensus: ConsensusEpsEstimate[];
+  snapshots: ConsensusEpsSnapshot[];
+}
+
 export interface TickerFinancials {
+  statementHistory?: StatementHistoryAttempt;
+  financialCurrency?: string;
   quote?: Quote;
+  quoteMetadata?: QuoteMetadata;
   quoteContributions?: QuoteContributionMap;
   fundamentals?: Fundamentals;
   profile?: CompanyProfile;
   annualStatements: FinancialStatement[];
   quarterlyStatements: FinancialStatement[];
   priceHistory: PricePoint[];
+  /** Present on extended statement history from the cloud. */
+  epsEstimates?: EpsEstimateHistory;
 }
 
 export interface OptionContract {
@@ -390,8 +551,9 @@ export interface OptionContract {
   lastPrice: number;
   change: number;
   percentChange: number;
-  volume: number;
-  openInterest: number;
+  /** Missing activity is unknown; an explicitly reported zero remains zero. */
+  volume?: number;
+  openInterest?: number;
   bid: number;
   ask: number;
   impliedVolatility: number;

package/src/types/headless.ts

@@ -1,5 +1,6 @@
 import type { AppConfig } from "./config";
 import type { DataProvider } from "./data-provider";
+import type { CapabilityInvoker } from "../capabilities/types";
 
 type GloomApiClientInstance = typeof import("../api-client").apiClient;
 
@@ -64,6 +65,11 @@ export interface HeadlessPaneContext {
   apiClient: HeadlessPaneApiClient;
   config: AppConfig;
   signal: AbortSignal;
+  /** Effective instance settings, after template creation and option normalization. */
+  settings?: Record<string, unknown>;
+  capabilities?: CapabilityInvoker;
+  /** Resolve locally remembered exchange identities without coupling plugins to storage. */
+  resolveInstrument?: (symbol: string) => Promise<{ symbol: string; exchange?: string }>;
 }
 
 export type HeadlessPaneRow = Record<string, unknown>;
@@ -86,6 +92,12 @@ export interface HeadlessPaneEntry {
 }
 
 interface HeadlessPaneResultBase {
+  /** False when usable output does not fully cover the requested inputs/depth. */
+  complete?: boolean;
+  /** Resolved inputs, including implicit peers or symbols parsed from an expression. */
+  symbols?: string[];
+  /** Missing inputs must remain visible even when other inputs returned rows. */
+  unavailableSymbols?: string[];
   errors?: string[];
   metadata?: Record<string, unknown>;
 }
@@ -126,6 +138,8 @@ export interface HeadlessSeriesPoint extends HeadlessPaneRow {
 export interface HeadlessSeries {
   id: string;
   label: string;
+  /** Explicit unit of the point values; report formatting does not rescale them. */
+  unit?: string;
   points: HeadlessSeriesPoint[];
 }
 
@@ -148,6 +162,15 @@ export interface HeadlessPaneResultByShape {
 
 export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = HeadlessPaneShape> {
   shape: Shape;
+  /** Optional discovery information; executors derive the rest from the definition. */
+  discovery?: {
+    id?: string;
+    aliases?: string[];
+    intents?: string[];
+    dataRequirements?: string[];
+    limitations?: string[];
+    screenshotReadiness?: "ready" | "partial" | "live-dom" | "unsupported";
+  };
   argument: HeadlessPaneArgumentDef;
   options: HeadlessPaneOptionDef[];
   columns?: HeadlessPaneColumn[];

package/src/types/instrument.ts

@@ -1,3 +1,6 @@
+/** Source price convention. Percent-of-par quantities are nominal face amounts;
+ * prices are percentage points per 100 face, independently of contract multiplier. */
+export type PriceBasis = "per-unit" | "percent-of-par";
 
 export interface BrokerContractRef {
   brokerId: string;
@@ -16,6 +19,14 @@ export interface BrokerContractRef {
   tradingClass?: string;
 }
 
+/** Public listing metadata supplied by a selected search result. */
+export interface TickerListingRef {
+  name: string;
+  exchange: string;
+  currency?: string;
+  type: string;
+}
+
 export interface InstrumentSearchResult {
   providerId: string;
   brokerInstanceId?: string;