gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/portfolio-list/column-values.ts

@@ -17,11 +17,14 @@ import {
   formatMarketPriceWithCurrency,
   formatMarketQuantity,
   formatSignedMarketPrice,
+  withCurrencyMinorDigits,
   withStablePriceDigits,
   type MarketFormatOptions,
 } from "../../../market-data/market/format";
 import {
   getActiveQuoteDisplay,
+  getCompletedRegularSessionDisplay,
+  getExtendedSessionDisplay,
   marketChangeColor,
   marketPriceColor,
   marketStateDot,
@@ -48,6 +51,14 @@ import {
   type PortfolioPositionPnl,
 } from "./position-metrics";
 import { isFiniteNumber } from "../../../utils/guards";
+import {
+  allocationFigures,
+  formatAllocationDrift,
+  formatAllocationWeight,
+  formatTradeUnits,
+  holdingTarget,
+  type AllocationFigures,
+} from "./allocation";
 
 export interface ColumnContext {
   activeTab?: string;
@@ -56,8 +67,14 @@ export interface ColumnContext {
   exchangeRates: Map<string, number>;
   /** Clock for quote age (per second while shown) and day-based columns. */
   now: number;
-  /** Gross market value of the collection; weights may trail it by about a second. */
+  /**
+   * The total a portfolio's weights divide by: its priced holdings at net
+   * market value plus its cash (see allocation.ts). It may trail the rows by
+   * about a second.
+   */
   portfolioTotalMarketValue?: number;
+  /** The portfolio's target weights in percent, by symbol. */
+  portfolioTargets?: Readonly<Record<string, number>>;
   supplementalVersion?: number;
   analystResearch?: Map<string, AnalystResearchData | null>;
   corporateActions?: Map<string, CorporateActionsData | null>;
@@ -169,19 +186,61 @@ function tradedQuoteDisplay(
   return valuation && metrics.valuesAtMark ? getActiveQuoteDisplay(quote) : valuation;
 }
 
+/**
+ * LAST, CHG and CHG% once the regular session is over, and in the pre-market
+ * while the quote carries the last session's close and move: that close and its
+ * move, frozen, because the EXT% column carries the extended print measured
+ * from that close. Until the close, and wherever no close is reported (a
+ * pre-market quote without it, venues without extended hours), the traded price
+ * as above.
+ * Valuation columns (DAY P&L, MKT VAL, weight, P&L) keep the live price.
+ * A watchlist's Avg Day averages this CHG%.
+ */
+export function headlineQuoteDisplay(
+  traded: ActiveQuoteDisplay | null,
+  quote: TickerFinancials["quote"],
+): ActiveQuoteDisplay | null {
+  return traded ? getCompletedRegularSessionDisplay(quote) ?? traded : null;
+}
+
+/** CHG% as shown: the headline's, else the quote's own when no position price is usable. */
+function headlineChangePercent(
+  headline: ActiveQuoteDisplay | null,
+  quote: TickerFinancials["quote"],
+): number | undefined {
+  if (headline) return headline.changePercent;
+  return quote ? (getCompletedRegularSessionDisplay(quote) ?? quote).changePercent : undefined;
+}
+
 function fiftyTwoWeekPosition(displayQuote: ActiveQuoteDisplay | null, quote: TickerFinancials["quote"]): number | null {
   const range = displayQuote ? liveFiftyTwoWeekRange(quote, displayQuote.price) : null;
   return displayQuote && range ? ((displayQuote.price - range.low) / (range.high - range.low)) * 100 : null;
 }
 
-function getActiveMarketValue(
+/** The row's weight, target, drift and trade, from its own live value and the pane's total. */
+function rowAllocation(
+  ticker: TickerRecord,
   activeQuote: ActiveQuoteDisplay | null,
-  positionMetrics: ReturnType<typeof getPortfolioPositionMetrics>,
+  baseMetrics: ReturnType<typeof getPortfolioPositionMetrics>,
   toBaseQuote: (value: number) => number,
-): number | null {
-  return resolvePortfolioMarketValue(positionMetrics, activeQuote ? toBaseQuote(activeQuote.price) : null)?.gross ?? null;
+  ctx: ColumnContext,
+): AllocationFigures & { unpriced: boolean } {
+  const held = baseMetrics.positionCount > 0;
+  const unitPrice = activeQuote ? toBaseQuote(activeQuote.price) : null;
+  const marketValue = held ? resolvePortfolioMarketValue(baseMetrics, unitPrice)?.net ?? null : 0;
+  return {
+    ...allocationFigures(
+      { held, marketValue, units: baseMetrics.totalShares, unitPrice },
+      ctx.portfolioTotalMarketValue,
+      holdingTarget(ctx.portfolioTargets, ticker.metadata.ticker),
+    ),
+    unpriced: held && marketValue == null,
+  };
 }
 
+/** A held position without a price says so where its allocation would be. */
+const UNPRICED = "n/a";
+
 export function resolvePortfolioPriceValue(
   activeQuote: ActiveQuoteDisplay | null,
   brokerMarkPrice: number | undefined,
@@ -215,6 +274,7 @@ export function getColumnValue(
   const positionMetrics = getPortfolioPositionMetrics(ticker, ctx.activeTab, quoteCurrency, undefined, quote);
   const activeQuote = getPortfolioQuoteDisplay(positionMetrics, quote);
   const displayQuote = tradedQuoteDisplay(positionMetrics, activeQuote, quote);
+  const headlineQuote = headlineQuoteDisplay(displayQuote, quote);
   const { positionCurrency, totalShares, totalCost, totalCostUnits, totalPriceUnits, multiplierHint, brokerMarkPrice } = positionMetrics;
   const baseMetrics = getPortfolioPositionMetrics(ticker, ctx.activeTab, quoteCurrency, {
     currency: ctx.baseCurrency,
@@ -270,12 +330,12 @@ export function getColumnValue(
     case "tags":
       return { text: ticker.metadata.tags.length > 0 ? ticker.metadata.tags.join(",") : "—" };
     case "price":
-      return resolvePortfolioPriceValue(displayQuote, brokerMarkPrice, displayQuote ? currentQuoteOptions : markOptions, col.width, quote?.marketState);
+      return resolvePortfolioPriceValue(headlineQuote, brokerMarkPrice, headlineQuote ? currentQuoteOptions : markOptions, col.width, quote?.marketState);
     case "change":
-      if (!displayQuote) return { text: "—" };
+      if (!headlineQuote) return { text: "—" };
       return {
-        text: formatSignedMarketPrice(displayQuote.change, { ...currentQuoteOptions, maxWidth: col.width }),
-        color: marketChangeColor(displayQuote.change, quote?.marketState),
+        text: formatSignedMarketPrice(headlineQuote.change, { ...currentQuoteOptions, maxWidth: col.width }),
+        color: marketChangeColor(headlineQuote.change, quote?.marketState),
       };
     case "bid":
       return { text: quote?.bid != null ? formatMarketPrice(quote.bid, { ...currentQuoteOptions, maxWidth: col.width }) : "—" };
@@ -297,10 +357,12 @@ export function getColumnValue(
       if (!isFiniteNumber(quote?.bidSize) && !isFiniteNumber(quote?.askSize)) return { text: "—" };
       return { text: `${formatCompact(quote?.bidSize)}/${formatCompact(quote?.askSize)}` };
     }
-    case "change_pct":
-      return displayQuote
-        ? { text: formatPercentRaw(displayQuote.changePercent), color: marketChangeColor(displayQuote.changePercent, quote?.marketState) }
-        : { text: quote ? formatPercentRaw(quote.changePercent) : "—", color: quote ? marketChangeColor(quote.changePercent, quote.marketState) : undefined };
+    case "change_pct": {
+      const changePercent = headlineChangePercent(headlineQuote, quote);
+      return quote
+        ? { text: formatPercentRaw(changePercent), color: marketChangeColor(changePercent, quote.marketState) }
+        : { text: "—" };
+    }
     case "volume":
       return { text: isFiniteNumber(quote?.volume) ? formatCompact(quote.volume, { fixedDecimals: true }) : "—" };
     case "dollar_volume": {
@@ -324,34 +386,50 @@ export function getColumnValue(
       const dividendYield = liveDividendYield(quote, fundamentals);
       return { text: dividendYield != null ? `${(dividendYield * 100).toFixed(2)}%` : "—" };
     }
-    case "ext_hours":
-      if ((quote?.marketState === "PRE" || quote?.marketState === "PREPRE") && quote.preMarketPrice != null) {
-        const changePercent = quote.preMarketChangePercent;
-        if (!isFiniteNumber(changePercent)) return { text: "—" };
-        return { text: formatPercentRaw(changePercent), color: priceColor(changePercent) };
-      }
-      if ((quote?.marketState === "POST" || quote?.marketState === "POSTPOST") && quote.postMarketPrice != null) {
-        const changePercent = quote.postMarketChangePercent;
-        if (!isFiniteNumber(changePercent)) return { text: "—" };
-        return { text: formatPercentRaw(changePercent), color: priceColor(changePercent) };
-      }
-      return { text: "—" };
+    case "ext_hours": {
+      const changePercent = getExtendedSessionDisplay(quote)?.changePercent;
+      if (!isFiniteNumber(changePercent)) return { text: "—" };
+      return { text: formatPercentRaw(changePercent), color: priceColor(changePercent) };
+    }
     case "side":
       return { text: positionSideLabel(ticker, ctx.activeTab) ?? "—" };
     case "shares":
       return { text: positionMetrics.positionCount > 0 ? formatMarketQuantity(totalShares, { ...formatOptions, maxWidth: col.width }) : "—" };
     case "avg_cost":
       if (totalCostUnits === 0 || !Number.isFinite(totalCost)) return { text: "—" };
-      return { text: formatMarketCost(totalCost / Math.abs(totalCostUnits), { ...formatOptions, maxWidth: col.width }) };
+      // A money cost keeps its currency's minor unit, as `portfolio show` prints it: 45.50, not 45.5.
+      return { text: formatMarketCost(totalCost / Math.abs(totalCostUnits), { ...withCurrencyMinorDigits(formatOptions, positionCurrency), maxWidth: col.width }) };
     case "cost_basis":
       if (baseMetrics.positionCount === 0 || !Number.isFinite(baseMetrics.totalCost)) return { text: "—" };
       return { text: formatCompact(baseMetrics.totalCost) };
-    case "mkt_value":
-      return { text: formatCompactAmount(resolvePortfolioMarketValue(baseMetrics, activeQuote ? toBaseQuote(activeQuote.price) : null)?.gross ?? Number.NaN) };
+    case "mkt_value": {
+      if (baseMetrics.positionCount === 0) return { text: "—" };
+      const marketValue = resolvePortfolioMarketValue(baseMetrics, activeQuote ? toBaseQuote(activeQuote.price) : null)?.gross;
+      return { text: marketValue == null ? UNPRICED : formatCompactAmount(marketValue) };
+    }
     case "weight": {
-      const marketValue = getActiveMarketValue(activeQuote, baseMetrics, toBaseQuote);
-      if (marketValue == null || !ctx.portfolioTotalMarketValue) return { text: "—" };
-      return { text: formatPercentRaw((marketValue / ctx.portfolioTotalMarketValue) * 100) };
+      const allocation = rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx);
+      return { text: allocation.unpriced ? UNPRICED : formatAllocationWeight(allocation.weight) };
+    }
+    case "target_weight":
+      return { text: formatAllocationWeight(holdingTarget(ctx.portfolioTargets, ticker.metadata.ticker)) };
+    case "drift": {
+      const allocation = rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx);
+      if (allocation.unpriced && allocation.targetWeight != null) return { text: UNPRICED };
+      const text = formatAllocationDrift(allocation.drift);
+      return { text, color: /[1-9]/.test(text) ? priceColor(allocation.drift!) : undefined };
+    }
+    case "trade": {
+      const allocation = rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx);
+      if (allocation.unpriced && allocation.targetWeight != null) return { text: UNPRICED };
+      const text = formatTradeUnits(allocation.tradeUnits, { units: totalShares, assetCategory: ticker.metadata.assetCategory });
+      return { text, color: /[1-9]/.test(text) ? priceColor(allocation.tradeUnits!) : undefined };
+    }
+    case "trade_value": {
+      const allocation = rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx);
+      if (allocation.unpriced && allocation.targetWeight != null) return { text: UNPRICED };
+      const text = formatCompactAmount(allocation.tradeValue ?? undefined, { signed: true });
+      return { text, color: /[1-9]/.test(text) ? priceColor(allocation.tradeValue!) : undefined };
     }
     case "day_pnl":
       if (activeQuote && isFiniteNumber(activeQuote.change) && Number.isFinite(positionMetrics.grossPriceUnits) && positionMetrics.grossPriceUnits !== 0) {
@@ -438,6 +516,7 @@ export function getSortValue(
   const positionMetrics = getPortfolioPositionMetrics(ticker, ctx.activeTab, quoteCurrency, undefined, quote);
   const activeQuote = getPortfolioQuoteDisplay(positionMetrics, quote);
   const displayQuote = tradedQuoteDisplay(positionMetrics, activeQuote, quote);
+  const headlineQuote = headlineQuoteDisplay(displayQuote, quote);
   const { positionCurrency, totalShares, totalCost, totalCostUnits, totalPriceUnits, brokerMarkPrice } = positionMetrics;
   const baseMetrics = getPortfolioPositionMetrics(ticker, ctx.activeTab, quoteCurrency, {
     currency: ctx.baseCurrency,
@@ -471,7 +550,7 @@ export function getSortValue(
     case "tags":
       return ticker.metadata.tags.join(",");
     case "price":
-      if (displayQuote) return displayQuote.price;
+      if (headlineQuote) return headlineQuote.price;
       if (brokerMarkPrice != null) return brokerMarkPrice;
       return null;
     case "bid":
@@ -490,9 +569,9 @@ export function getSortValue(
         ? (quote?.bidSize ?? 0) + (quote?.askSize ?? 0)
         : null;
     case "change":
-      return displayQuote?.change ?? null;
+      return headlineQuote?.change ?? null;
     case "change_pct":
-      return displayQuote?.changePercent ?? null;
+      return headlineChangePercent(headlineQuote, quote) ?? null;
     case "volume":
       return quote?.volume ?? null;
     case "dollar_volume":
@@ -512,13 +591,7 @@ export function getSortValue(
     case "dividend_yield":
       return liveDividendYield(quote, fundamentals) ?? null;
     case "ext_hours":
-      if ((quote?.marketState === "PRE" || quote?.marketState === "PREPRE") && quote.preMarketPrice != null) {
-        return quote.preMarketChangePercent ?? null;
-      }
-      if ((quote?.marketState === "POST" || quote?.marketState === "POSTPOST") && quote.postMarketPrice != null) {
-        return quote.postMarketChangePercent ?? null;
-      }
-      return null;
+      return getExtendedSessionDisplay(quote)?.changePercent ?? null;
     case "side":
       return positionSideLabel(ticker, ctx.activeTab);
     case "shares":
@@ -529,12 +602,16 @@ export function getSortValue(
       return baseMetrics.positionCount > 0 && Number.isFinite(baseMetrics.totalCost) ? baseMetrics.totalCost : null;
     case "mkt_value":
       return resolvePortfolioMarketValue(baseMetrics, activeQuote ? toBaseQuote(activeQuote.price) : null)?.gross ?? null;
-    case "weight": {
-      const marketValue = getActiveMarketValue(activeQuote, baseMetrics, toBaseQuote);
-      return marketValue != null && ctx.portfolioTotalMarketValue
-        ? (marketValue / ctx.portfolioTotalMarketValue) * 100
-        : null;
-    }
+    case "weight":
+      return rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx).weight;
+    case "target_weight":
+      return holdingTarget(ctx.portfolioTargets, ticker.metadata.ticker) ?? null;
+    case "drift":
+      return rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx).drift;
+    case "trade":
+      return rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx).tradeUnits;
+    case "trade_value":
+      return rowAllocation(ticker, activeQuote, baseMetrics, toBaseQuote, ctx).tradeValue;
     case "day_pnl":
       if (activeQuote && isFiniteNumber(activeQuote.change) && Number.isFinite(positionMetrics.grossPriceUnits) && positionMetrics.grossPriceUnits !== 0) {
         return toBaseQuote(totalPriceUnits * activeQuote.change);

package/src/plugins/builtin/portfolio-list/headless.ts

@@ -3,6 +3,7 @@ import type {
   HeadlessPaneColumn,
   HeadlessPaneContext,
   HeadlessPaneDefinition,
+  HeadlessPaneRow,
   HeadlessRowsResult,
 } from "../../../types/plugin";
 import type { TickerRecord } from "../../../types/ticker";
@@ -10,10 +11,20 @@ import { formatNumber, formatPercentRaw } from "../../../utils/format";
 import {
   findCollection,
   loadCollectionQuotes,
+  valuePortfolioAllocation,
   valuePortfolioPositions,
   type CollectionMatch,
 } from "./cli/render";
+import {
+  CASH_SYMBOL,
+  describeTargetSum,
+  formatAllocationDrift,
+  formatAllocationWeight,
+  formatTradeUnits,
+} from "./allocation";
+import { currencyMinorDigits, formatMarketPrice, formatMarketQuantity } from "../../../market-data/market/format";
 import { resolvePortfolioTotalsCurrency } from "./summary/totals";
+import { quoteFreshnessFields } from "../shared/report-freshness";
 
 const DEFAULT_ROW_LIMIT = 50;
 const MAX_ROW_LIMIT = 200;
@@ -21,22 +32,50 @@ const MAX_ROW_LIMIT = 200;
 const LISTED_COLLECTION_IDS = 12;
 
 const amount = (value: unknown) => formatNumber(typeof value === "number" ? value : undefined, 2);
+/** Market values and trades in whole units, as `portfolio show` prints them. */
+const wholeAmount = (value: unknown) => formatNumber(typeof value === "number" ? value : undefined, 0);
+const signedAmount = (value: unknown) => (
+  typeof value === "number" && Number.isFinite(value) ? `${value > 0 && /[1-9]/.test(wholeAmount(value)) ? "+" : ""}${wholeAmount(value)}` : formatNumber(undefined)
+);
 const percent = (value: unknown) => formatPercentRaw(typeof value === "number" ? value : undefined);
-const share = (value: unknown) => (
-  typeof value === "number" && Number.isFinite(value) ? `${formatNumber(value, 2)}%` : formatNumber(undefined)
+const weight = (value: unknown) => formatAllocationWeight(typeof value === "number" ? value : null);
+const drift = (value: unknown) => formatAllocationDrift(typeof value === "number" ? value : null);
+const quantity = (value: unknown, row: HeadlessPaneRow) => (
+  typeof value === "number" ? formatMarketQuantity(value, { assetCategory: textOf(row.assetCategory) }) : formatNumber(undefined)
+);
+const tradeUnits = (value: unknown, row: HeadlessPaneRow) => (
+  typeof value === "number" ? formatTradeUnits(value, { units: finite(row.shares) ?? 0, assetCategory: textOf(row.assetCategory) }) : formatNumber(undefined)
 );
+/** Money per unit at the currency's minor digits: $230.00, not 230. */
+const unitMoney = (currencyKey: string) => (value: unknown, row: HeadlessPaneRow) => (
+  typeof value === "number"
+    ? formatMarketPrice(value, { assetCategory: textOf(row.assetCategory), minimumFractionDigits: Math.min(2, currencyMinorDigits(textOf(row[currencyKey]))) })
+    : formatNumber(undefined)
+);
+
+function textOf(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
 
 const POSITION_COLUMNS: HeadlessPaneColumn[] = [
   { key: "symbol", header: "Ticker" },
   { key: "name", header: "Name" },
-  { key: "shares", header: "Qty", align: "right" },
-  { key: "avgCost", header: "Avg Cost", align: "right", description: "Per unit, in the position's currency." },
-  { key: "price", header: "Last", align: "right", description: "In the quote's currency." },
+  { key: "shares", header: "Qty", align: "right", format: quantity },
+  { key: "avgCost", header: "Avg Cost", align: "right", format: unitMoney("positionCurrency"), description: "Per unit, in the position's currency." },
+  { key: "price", header: "Last", align: "right", format: unitMoney("priceCurrency"), description: "In the quote's currency." },
   { key: "priceCurrency", header: "Ccy" },
   { key: "changePercent", header: "Chg", align: "right", format: percent },
-  { key: "marketValue", header: "Mkt Val", align: "right", format: amount, description: "In the portfolio's currency; negative for shorts." },
+  { key: "marketValue", header: "Mkt Val", align: "right", format: wholeAmount, description: "In the portfolio's currency; negative for shorts." },
   { key: "unrealizedPnl", header: "P&L", align: "right", format: amount, description: "Unrealized, in the portfolio's currency." },
-  { key: "weight", header: "Weight", align: "right", format: share, description: "Percent of the portfolio's gross market value." },
+  { key: "weight", header: "Weight", align: "right", format: weight, description: "Percent of the total value, cash included; unpriced holdings are left out." },
+];
+
+/** Shown once the portfolio has a target weight. */
+const TARGET_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "targetWeight", header: "Target", align: "right", format: weight, description: "Target weight, in percent." },
+  { key: "drift", header: "Drift", align: "right", format: drift, description: "Weight minus target, in percentage points." },
+  { key: "tradeShares", header: "Trade", align: "right", format: tradeUnits, description: "Units to buy (+) or sell (-) to reach the target at the current price." },
+  { key: "tradeValue", header: "Trade Value", align: "right", format: signedAmount, description: "The trade in the portfolio's currency." },
 ];
 
 const WATCHLIST_COLUMNS: HeadlessPaneColumn[] = [
@@ -97,26 +136,36 @@ async function portfolioHoldings(
   const currency = resolvePortfolioTotalsCurrency(target.portfolio, ctx.config.baseCurrency);
   const quotes = await loadCollectionQuotes(tickers, target, ctx.marketData);
   ctx.signal.throwIfAborted();
+  const toBase = createBaseConverter(ctx.marketData, currency);
   const valuation = await valuePortfolioPositions({
     tickers,
     quotes,
     portfolioId: target.id,
     currency,
     baseCurrency: ctx.config.baseCurrency,
-    toBase: createBaseConverter(ctx.marketData, currency),
+    toBase,
   });
+  const { allocation, cash } = await valuePortfolioAllocation({ valuation, portfolio: resolved.portfolio, account: resolved.account, toBase });
   ctx.signal.throwIfAborted();
 
+  const allocationBySymbol = new Map(allocation.rows.map((row) => [row.symbol, row]));
   const held = valuation.positions.filter((entry) => entry.position);
   const gross = held.reduce((sum, entry) => sum + Math.abs(finite(entry.row.marketValue) ?? 0), 0);
   const sum = (key: string) => held.reduce((total, entry) => total + (finite(entry.row[key]) ?? 0), 0);
+  const seen = new Set<string>();
   const rows = held
     .map(({ ticker, activeQuote, row }) => {
       const marketValue = finite(row.marketValue);
+      // A ticker held in several lots carries its allocation on its first row.
+      const figures = seen.has(ticker.metadata.ticker) ? undefined : allocationBySymbol.get(ticker.metadata.ticker);
+      seen.add(ticker.metadata.ticker);
       return {
+        ...quoteFreshnessFields(quotes.get(ticker.metadata.ticker)),
+        updatedAt: quotes.get(ticker.metadata.ticker)?.lastUpdated ?? null,
         symbol: ticker.metadata.ticker,
         name: ticker.metadata.name ?? null,
         exchange: ticker.metadata.exchange || null,
+        assetCategory: ticker.metadata.assetCategory ?? null,
         shares: finite(row.shares),
         avgCost: finite(row.avgCost),
         positionCurrency: row.positionCurrency ?? null,
@@ -125,7 +174,11 @@ async function portfolioHoldings(
         changePercent: finite(activeQuote?.changePercent),
         marketValue,
         unrealizedPnl: finite(row.unrealizedPnl),
-        weight: marketValue != null && gross > 0 ? (Math.abs(marketValue) / gross) * 100 : null,
+        weight: figures?.weight ?? null,
+        targetWeight: figures?.targetWeight ?? null,
+        drift: figures?.drift ?? null,
+        tradeShares: figures?.tradeUnits ?? null,
+        tradeValue: figures?.tradeValue ?? null,
       };
     })
     // Largest exposure first; a position without a market value sorts last.
@@ -133,16 +186,39 @@ async function portfolioHoldings(
       exposure(right.marketValue) - exposure(left.marketValue)
       || left.symbol.localeCompare(right.symbol)
     ));
-  const shown = rows.slice(0, limit);
+  const shown: HeadlessPaneRow[] = rows.slice(0, limit);
+  // The cash line follows the positions, whatever the limit.
+  if (allocation.cash) {
+    shown.push({
+      symbol: CASH_SYMBOL,
+      name: cash?.source === "broker" ? "Cash (broker account)" : "Cash",
+      priceCurrency: cash?.currency ?? null,
+      marketValue: finite(allocation.cash.value),
+      weight: allocation.cash.weight,
+      targetWeight: allocation.cash.targetWeight,
+      drift: allocation.cash.drift,
+      tradeShares: null,
+      tradeValue: allocation.cash.tradeValue,
+    });
+  }
   const unavailable = [...new Set([...valuation.unavailableMarketValue, ...valuation.unavailablePnl])];
   const broker = !!(target.portfolio.brokerId || target.portfolio.brokerInstanceId);
+  const showTargets = allocation.targetSum != null;
+  const targetNote = describeTargetSum(allocation.targetSum);
+  const notices = [
+    ...(rows.length > limit
+      ? [`${rows.length - limit} more position${rows.length - limit === 1 ? "" : "s"} not shown; totals include every position.`]
+      : []),
+    ...(targetNote ? [targetNote] : []),
+  ];
 
   return {
-    columns: POSITION_COLUMNS,
+    freshness: { source: broker ? "Your broker account and Gloom Cloud" : "Local portfolio and Gloom Cloud" },
+    columns: showTargets ? [...POSITION_COLUMNS, ...TARGET_COLUMNS] : POSITION_COLUMNS,
     rows: shown,
     complete: unavailable.length === 0,
     ...(unavailable.length
-      ? { errors: [`No market value or P&L for ${unavailable.join(", ")}; totals leave them out.`] }
+      ? { errors: [`No market value or P&L for ${unavailable.join(", ")}; totals and weights leave them out.`] }
       : {}),
     metadata: {
       collection: { kind: "portfolio", id: target.id, name: target.name, broker },
@@ -153,10 +229,13 @@ async function portfolioHoldings(
         grossMarketValue: gross,
         costBasis: sum("costBasis"),
         unrealizedPnl: valuation.totalPnl,
+        cash: allocation.cash ? finite(allocation.cash.value) : null,
+        total: allocation.total,
       },
-      ...(rows.length > shown.length
-        ? { notices: [`${rows.length - shown.length} more position${rows.length - shown.length === 1 ? "" : "s"} not shown; totals include every position.`] }
-        : {}),
+      ...(cash ? { cash } : {}),
+      ...(showTargets ? { targetSum: allocation.targetSum } : {}),
+      unpricedCount: allocation.unpriced.length,
+      ...(notices.length > 0 ? { notices } : {}),
     },
   };
 }
@@ -174,6 +253,8 @@ async function watchlistHoldings(
   const rows = tickers.map((ticker) => {
     const quote = quotes.get(ticker.metadata.ticker);
     return {
+      ...quoteFreshnessFields(quote),
+      updatedAt: quote?.lastUpdated ?? null,
       symbol: ticker.metadata.ticker,
       name: ticker.metadata.name ?? null,
       exchange: ticker.metadata.exchange || null,
@@ -184,6 +265,7 @@ async function watchlistHoldings(
   });
   const shown = rows.slice(0, limit);
   return {
+    freshness: { source: "Local watchlist and Gloom Cloud" },
     columns: WATCHLIST_COLUMNS,
     rows: shown,
     metadata: {
@@ -204,7 +286,7 @@ async function watchlistHoldings(
 export const collectionHoldingsHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
   description:
-    "Positions held in a portfolio, broker or manual: symbol, quantity, average cost, last price, market value, unrealized P&L and weight, largest first, with totals. For a watchlist, its tickers with quotes. Takes a portfolio or watchlist ID; the first portfolio when omitted.",
+    "Positions held in a portfolio, broker or manual: symbol, quantity, average cost, last price, market value, unrealized P&L and weight of the total with cash, largest first, then the cash line and totals. With target weights set, each row adds its target, drift and the trade to reach it. For a watchlist, its tickers with quotes. Takes a portfolio or watchlist ID; the first portfolio when omitted.",
   discovery: {
     dataRequirements: ["Local portfolios, watchlists and synced broker positions; current quotes"],
     limitations: ["Unrealized P&L on current positions; excludes realized trades, distributions and cash flows"],

package/src/plugins/builtin/portfolio-list/index.tsx

@@ -9,6 +9,7 @@ import {
 import { portfolioCliCommand } from "./cli/portfolio-command";
 import { watchlistCliCommand } from "./cli/watchlist-command";
 import { collectionHoldingsHeadless } from "./headless";
+import { findCollection } from "./cli/render";
 import {
   LIVE_STREAMING_QUICK_SETTING,
   withLiveStreamingSetting,
@@ -30,8 +31,13 @@ function resolveCollectionIdForKind(context: PaneTemplateContext, kind: "portfol
 function createCollectionPaneInstance(
   context: PaneTemplateContext,
   kind?: "portfolio" | "watchlist",
+  argument?: string,
 ): PaneTemplateInstanceConfig | null {
-  const collectionId = kind ? resolveCollectionIdForKind(context, kind) : resolveCollectionPaneId(context);
+  // `PF Retirement` (or `shot PF Retirement`) opens the collection it names.
+  const named = argument?.trim() ? findCollection(context.config, argument) : null;
+  const collectionId = named && (!kind || named.kind === kind)
+    ? named.id
+    : kind ? resolveCollectionIdForKind(context, kind) : resolveCollectionPaneId(context);
   return collectionId ? { params: { collectionId } } : null;
 }
 
@@ -39,6 +45,7 @@ export const portfolioListModule: PluginModule = {
   panes: [
     {
       id: "portfolio-list",
+      reportFreshness: { source: "Local portfolio and Gloom Cloud" },
       name: "Portfolio",
       icon: "P",
       component: PortfolioListPane,
@@ -75,11 +82,15 @@ export const portfolioListModule: PluginModule = {
       paneId: "portfolio-list",
       label: "Collection Pane",
       description: "Open another pane for the current portfolio or watchlist",
-      keywords: ["portfolio", "watchlist", "collection", "pane", "list"],
+      // Phrases rather than bare words, so `fn rebalance` and `fn target` keep resolving where they did.
+      keywords: [
+        "portfolio", "watchlist", "collection", "pane", "list",
+        "portfolio rebalance", "allocation drift", "target weights", "asset allocation", "cash balance",
+      ],
       shortcut: { prefix: "PF" },
       headless: collectionHoldingsHeadless,
       canCreate: (context) => resolveCollectionPaneId(context) !== null,
-      createInstance: (context) => createCollectionPaneInstance(context),
+      createInstance: (context, options) => createCollectionPaneInstance(context, undefined, options?.arg),
     },
     {
       id: "new-portfolio-pane",

package/src/plugins/builtin/portfolio-list/live-valuation.ts

@@ -1,6 +1,7 @@
 import type { AnalystResearchData, Fundamentals, Quote } from "../../../types/financials";
 import { hasLikelyQuoteUnitMismatch } from "../../../utils/currency-units";
 import { selectMarketCapitalization, type MarketCapitalization } from "../../../utils/market-capitalization";
+import { priceEarningsOnEarnings, type PriceEarnings } from "../../../utils/price-earnings";
 
 /**
  * Price-derived statistics repriced from the current quote with the base
@@ -53,13 +54,14 @@ function repriceMultiple(
   return price / perShare;
 }
 
-/** Trailing P/E over the current price. Zero or negative EPS keeps the stored multiple. */
-export function liveTrailingPE(quote: Quote | null | undefined, fundamentals: Fundamentals | undefined): number | undefined {
-  return repriceMultiple(fundamentals?.trailingPE, fundamentals?.eps, quote, fundamentals);
+/** Trailing P/E over the current price; not meaningful when the trailing EPS is zero or a loss. */
+export function liveTrailingPE(quote: Quote | null | undefined, fundamentals: Fundamentals | undefined): PriceEarnings | undefined {
+  return priceEarningsOnEarnings(repriceMultiple(fundamentals?.trailingPE, fundamentals?.eps, quote, fundamentals), fundamentals?.eps);
 }
 
-export function liveForwardPE(quote: Quote | null | undefined, fundamentals: Fundamentals | undefined): number | undefined {
-  return repriceMultiple(fundamentals?.forwardPE, fundamentals?.forwardEps, quote, fundamentals);
+/** Forward P/E over the current price; not meaningful when the forward EPS behind it is zero or a loss. */
+export function liveForwardPE(quote: Quote | null | undefined, fundamentals: Fundamentals | undefined): PriceEarnings | undefined {
+  return priceEarningsOnEarnings(repriceMultiple(fundamentals?.forwardPE, fundamentals?.forwardEps, quote, fundamentals), fundamentals?.forwardEps);
 }
 
 /** Forward dividend yield over the current price, as a ratio like the stored yield. */