zframes 0.8.1 → 0.9.0

package/dist/index.js

@@ -78,6 +78,34 @@ var FrameStyleSchema = z2.object({
 }).describe(
   "Per-frame cosmetic overrides \u2014 accent, surface tint, glass, corners, border, padding, shadow \u2014 for THIS card only. Every field optional; omit to inherit the dashboard `theme`/`appearance`."
 );
+var CURRENCY_CODES = [
+  "USD",
+  "THB",
+  "EUR",
+  "GBP",
+  "JPY",
+  "CNY",
+  "KRW",
+  "SGD",
+  "AUD",
+  "CAD",
+  "CHF",
+  "INR",
+  "IDR",
+  "MYR",
+  "PHP",
+  "HKD",
+  "BRL",
+  "MXN",
+  "ZAR"
+];
+var CurrencySchema = z2.object({
+  code: z2.enum(CURRENCY_CODES).default("USD").describe(
+    'Currency every money figure on the dashboard is displayed in, converted from USD at the live ECB reference rate \u2014 e.g. "THB" shows a Thai-baht board. Non-money figures (percentages, counts, rates) are unaffected, and US-macro series (Treasury yields, CPI, the national debt) stay in USD because converting them would be meaningless.'
+  )
+}).describe(
+  "Dashboard-wide display currency. Frames may override it per card via their own `currency` field."
+);
 var FrameInstanceSchema = z2.object({
   id: z2.string().describe("Unique instance id within the dashboard"),
   frame: z2.string().describe("Name of a registered frame"),
@@ -87,6 +115,9 @@ var FrameInstanceSchema = z2.object({
   title: z2.string().optional().describe(
     'Optional custom card title. Omit it to use the frame\'s own polished default label (its catalogue `label`, e.g. "OI by Strike") \u2014 that is the norm. Only set this for a genuinely instance-specific label the default can\'t know, e.g. the ticker on a price-chart ("TSLA") or which outlet a news-feed shows. Never abbreviate. Ignored by chrome-less frames like heading.'
   ),
+  currency: z2.enum(CURRENCY_CODES).optional().describe(
+    'Display currency for THIS card only, overriding the dashboard-wide `currency` (e.g. keep one card in "USD" on a baht board). Omit to inherit. Purely presentational \u2014 it converts USD figures for display. Note it is NOT the same as a `config.currency` some frames have (the metals LBMA-fix frames use that to pick which published fix series to READ); this field never changes which data is fetched.'
+  ),
   position: GridPositionSchema,
   layouts: z2.record(z2.string(), GridPositionSchema).optional().describe(
     'Per-mode layout overrides keyed by grid.mode (e.g. "flow-horizontal"). `position` is the canonical flow-vertical layout; this holds the other modes\' placements so each layout mode keeps its own independent arrangement. Editor-managed \u2014 agents only need to set `position`.'
@@ -267,6 +298,7 @@ var DashboardSpecSchema = z2.preprocess(
       downColor: "#ff6b81",
       surface: "dark"
     }),
+    currency: CurrencySchema.default({ code: "USD" }),
     typography: TypographySchema.default({
       fontFamily: "sans",
       numericStyle: "proportional",
@@ -484,6 +516,9 @@ function validateCustomUrl(url) {
 
 // ../frames/src/schemas.ts
 var widgetIcon = (name) => `/widget-icons/${name}.png`;
+var venueField = () => z3.enum(["hyperliquid", "bitkub"]).optional().describe(
+  `Which exchange to source this card from \u2014 "hyperliquid" (default: crypto + HIP-3 stock/commodity perps, USD) or "bitkub" (Thailand's largest exchange, THB-quoted, the venue where KUB trades). Omit for the default. Use venue-native symbols: Bitkub lists bare tickers like "KUB"/"BTC" and has no HIP-3 stock perps.`
+);
 var SOURCES = {
   hyperliquid: { name: "Hyperliquid", url: "https://hyperliquid.xyz" },
   defillama: { name: "DeFiLlama", url: "https://defillama.com" },
@@ -520,7 +555,17 @@ var SOURCES = {
     name: "GeckoTerminal",
     url: "https://www.geckoterminal.com"
   },
-  blockchair: { name: "Blockchair", url: "https://blockchair.com" }
+  blockchair: { name: "Blockchair", url: "https://blockchair.com" },
+  bitkub: { name: "Bitkub", url: "https://www.bitkub.com" },
+  goldApi: { name: "gold-api.com", url: "https://gold-api.com" },
+  lbma: {
+    name: "LBMA",
+    url: "https://www.lbma.org.uk/prices-and-data/precious-metal-prices"
+  },
+  cftc: {
+    name: "CFTC",
+    url: "https://www.cftc.gov/MarketReports/CommitmentsofTraders/index.htm"
+  }
 };
 var clockMeta = defineFrameMeta({
   name: "clock",
@@ -618,14 +663,17 @@ var priceChartMeta = defineFrameMeta({
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Live animated price chart (candlestick or line) for one symbol \u2014 canvas-rendered at 60fps via liveline, streaming live off the Hyperliquid WebSocket. Works for any HIP-3 perp \u2014 stocks (xyz:TSLA), indices (xyz:SP500), commodities (xyz:GOLD) \u2014 and crypto (BTC). The centerpiece frame.",
   capabilities: ["ohlcv", "quote-stream"],
-  source: SOURCES.hyperliquid,
+  // Either venue can back this card (see `venue`), so both are credited — the
+  // badge is static meta and can't know which one a given instance pinned.
+  source: [SOURCES.hyperliquid, SOURCES.bitkub],
   schema: z3.object({
     symbol: z3.string().min(1).describe(
       'Hyperliquid symbol to chart. HIP-3 cross-asset: stocks "xyz:TSLA"/"xyz:NVDA", indices "xyz:SP500"/"xyz:XYZ100", commodities "xyz:GOLD"/"xyz:CL", FX "xyz:EUR". Crypto: "BTC", "ETH".'
     ),
     interval: z3.enum(["1m", "5m", "15m", "1h", "4h", "1d"]).default("1h").describe("Candle interval."),
     mode: z3.enum(["candle", "line"]).default("candle").describe("Candlestick or smooth line rendering."),
-    color: z3.string().default("#8b8df9").describe("Accent color (hex). The whole palette derives from it.")
+    color: z3.string().default("#8b8df9").describe("Accent color (hex). The whole palette derives from it."),
+    venue: venueField()
   })
 });
 var priceLivelineMeta = defineFrameMeta({
@@ -672,9 +720,11 @@ var topMoversMeta = defineFrameMeta({
   layout: { w: 5, h: 3, minW: 3, minH: 3 },
   description: "Today's biggest stock and commodity HIP-3 gainers and losers (no bare crypto), side by side with current price and 24h change.",
   capabilities: ["day-stats"],
-  source: SOURCES.hyperliquid,
+  // Either venue can back this card (see `venue`) — both are credited.
+  source: [SOURCES.hyperliquid, SOURCES.bitkub],
   schema: z3.object({
-    count: z3.number().int().min(3).max(10).default(5).describe("How many gainers and losers to list (each).")
+    count: z3.number().int().min(3).max(10).default(5).describe("How many gainers and losers to list (each)."),
+    venue: venueField()
   })
 });
 var tvlTreemapMeta = defineFrameMeta({
@@ -2238,6 +2288,23 @@ var chainActivityMeta = defineFrameMeta({
   source: SOURCES.blockchair,
   schema: z3.object({})
 });
+var orderBookDepthMeta = defineFrameMeta({
+  name: "order-book-depth",
+  label: "Order Book",
+  category: "markets",
+  iconUrl: widgetIcon("order-book-depth"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Live two-sided order book for one Bitkub market \u2014 bid and ask ladders with cumulative resting size, plus the mid price and spread. Shows where the resting liquidity actually sits, which a price feed alone can't. Prices in Thai baht. Keyless (Bitkub public API).",
+  capabilities: ["order-book"],
+  source: SOURCES.bitkub,
+  schema: z3.object({
+    symbol: z3.string().min(1).default("KUB").describe(
+      'Base asset ticker as listed on the venue, e.g. "KUB", "BTC", "ETH" \u2014 the quote asset is implied (THB on Bitkub).'
+    ),
+    venue: venueField(),
+    levels: z3.number().int().min(3).max(25).default(10).describe("How many price levels to show per side.")
+  })
+});
 var nftTreemapMeta = defineFrameMeta({
   name: "nft-treemap",
   label: "NFT Treemap",
@@ -3085,9 +3152,7 @@ var optionsOiLadderHeatmapMeta = defineFrameMeta({
   source: SOURCES.deribit,
   schema: z3.object({
     currency: z3.enum(["BTC", "ETH"]).default("BTC").describe("Which Deribit options book \u2014 BTC or ETH."),
-    expiries: z3.number().int().min(3).max(16).default(8).describe(
-      "How many upcoming expiries (nearest-first) to show as rows."
-    ),
+    expiries: z3.number().int().min(3).max(16).default(8).describe("How many upcoming expiries (nearest-first) to show as rows."),
     buckets: z3.number().int().min(6).max(20).default(10).describe(
       "How many strike bands (columns) to bin open interest into, spanning the shown expiries' strike range."
     )
@@ -3564,7 +3629,457 @@ var predictionMarketsBubbleMeta = defineFrameMeta({
     limit: z3.number().int().min(3).max(20).default(10).describe("How many markets (by volume) to show.")
   })
 });
+var METAL_SYMBOLS = ["XAU", "XAG", "XPT", "XPD", "HG"];
+var FIXED_METALS = ["XAU", "XAG", "XPT", "XPD"];
+var METAL_NAMES = "XAU gold, XAG silver, XPT platinum, XPD palladium, HG copper (copper is quoted per pound; the rest per troy ounce)";
+var FIXED_METAL_NAMES = "XAU gold, XAG silver, XPT platinum, XPD palladium. Gold and silver go back to 1968, platinum and palladium to 1990.";
+var yearsField = (dflt, describe) => z3.number().int().min(1).max(58).default(dflt).describe(describe);
+var metalsBoardMeta = defineFrameMeta({
+  name: "metals-board",
+  label: "Metals Board",
+  category: "metals",
+  iconUrl: widgetIcon("metals-board"),
+  layout: { w: 3, h: 4, minW: 2, minH: 3 },
+  description: "Live spot board for the metals complex \u2014 gold, silver, platinum, palladium and copper \u2014 each with its current price and its move against the most recent London fix. Keyless spot quotes; the metals equivalent of a crypto ticker list.",
+  capabilities: ["metal-spot"],
+  source: SOURCES.goldApi,
+  schema: z3.object({
+    symbols: z3.array(z3.enum(METAL_SYMBOLS)).min(1).max(5).default([...METAL_SYMBOLS]).describe(`Metals to list, in display order. ${METAL_NAMES}.`),
+    showChange: z3.boolean().default(true).describe(
+      "Show each metal's percent move against the latest London fix. The change appears once the fix history has loaded (a few seconds after first paint)."
+    )
+  })
+});
+var metalPriceMeta = defineFrameMeta({
+  name: "metal-price",
+  label: "Metal Price",
+  category: "metals",
+  iconUrl: widgetIcon("metal-price"),
+  layout: { w: 3, h: 2, minW: 2, minH: 2 },
+  description: "One metal's live spot price as a headline number, in the weight unit you pick (troy ounce, gram, kilogram or tola). The single-asset hero card for a gold or silver dashboard.",
+  capabilities: ["metal-spot"],
+  source: SOURCES.goldApi,
+  schema: z3.object({
+    symbol: z3.enum(METAL_SYMBOLS).default("XAU").describe(`Metal to price. ${METAL_NAMES}.`),
+    unit: z3.enum(["ounce", "gram", "kilogram", "tola"]).default("ounce").describe(
+      "Weight unit the headline price is quoted in. Troy ounce is the market convention; gram and kilogram suit retail bullion, tola is the South Asian bar unit (11.6638 g). Ignored for copper, which quotes per pound."
+    ),
+    showFix: z3.boolean().default(true).describe(
+      "Show the latest London fix underneath as the reference the change is measured from."
+    )
+  })
+});
+var metalValueMeta = defineFrameMeta({
+  name: "metal-value",
+  label: "Metal Holding Value",
+  category: "metals",
+  iconUrl: widgetIcon("metal-value"),
+  layout: { w: 3, h: 2, minW: 2, minH: 2 },
+  description: "What a physical holding is worth right now: a weight you own, multiplied by live spot. Set the weight and unit once and the card revalues itself as the metal moves.",
+  capabilities: ["metal-spot"],
+  source: SOURCES.goldApi,
+  schema: z3.object({
+    symbol: z3.enum(METAL_SYMBOLS).default("XAU").describe(`Metal held. ${METAL_NAMES}.`),
+    weight: z3.number().positive().default(1).describe("How much of the metal is held, in `unit`."),
+    unit: z3.enum(["ounce", "gram", "kilogram", "tola"]).default("ounce").describe(
+      "Unit the weight is expressed in \u2014 troy ounce, gram, kilogram, or tola (11.6638 g)."
+    )
+  })
+});
+var metalPriceChartMeta = defineFrameMeta({
+  name: "metal-price-chart",
+  label: "Metal Price Chart",
+  category: "metals",
+  iconUrl: widgetIcon("metal-price-chart"),
+  layout: { w: 6, h: 4, minW: 4, minH: 3 },
+  description: "Daily London fix history for one or more metals \u2014 the benchmark price the physical market settles against, published by the LBMA and running back to 1968 for gold and silver. Set the window in years and switch to a log axis for multi-decade views.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbols: z3.array(z3.enum(FIXED_METALS)).min(1).max(4).default(["XAU"]).describe(`Metals to chart. ${FIXED_METAL_NAMES}`),
+    currency: z3.enum(["USD", "GBP", "EUR"]).default("USD").describe(
+      "Which published fix SERIES to read \u2014 the LBMA fixes each metal in all three, and they are separate prints, not conversions of one another (EUR only exists from 1999). This is a data choice, not a display one: to change what the card renders money in, set the frame instance's own `currency` (sibling of `config`) or the dashboard's. A USD fix follows that display currency; a GBP/EUR fix is shown as published."
+    ),
+    years: yearsField(5, "How many years of daily fixes to chart."),
+    logScale: z3.boolean().default(false).describe(
+      "Use a logarithmic price axis \u2014 the honest way to read a multi-decade series, where a move from $35 to $350 is the same tenfold step as $350 to $3,500."
+    )
+  })
+});
+var metalDrawdownMeta = defineFrameMeta({
+  name: "metal-drawdown",
+  label: "Metal Drawdown",
+  category: "metals",
+  iconUrl: widgetIcon("metal-drawdown"),
+  layout: { w: 5, h: 4, minW: 3, minH: 3 },
+  description: "How far a metal sits below its running all-time high, charted through history. Gold's decades-long post-1980 underwater stretch is the clearest picture of what a real bear market in bullion looks like.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to chart. ${FIXED_METAL_NAMES}`),
+    years: yearsField(20, "How many years of drawdown history to chart.")
+  })
+});
+var metalAnnualReturnsMeta = defineFrameMeta({
+  name: "metal-annual-returns",
+  label: "Metal Annual Returns",
+  category: "metals",
+  iconUrl: widgetIcon("metal-annual-returns"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "Calendar-year percent return per year as diverging bars \u2014 green up years, red down years \u2014 from the LBMA fix history. The at-a-glance record of how often, and how hard, a metal actually delivers.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to chart. ${FIXED_METAL_NAMES}`),
+    years: z3.number().int().min(3).max(58).default(15).describe(
+      "How many calendar years of returns to show, most recent last."
+    )
+  })
+});
+var metalSeasonalityMeta = defineFrameMeta({
+  name: "metal-seasonality",
+  label: "Metal Seasonality",
+  category: "metals",
+  iconUrl: widgetIcon("metal-seasonality"),
+  layout: { w: 6, h: 4, minW: 4, minH: 3 },
+  description: "Month-by-year heatmap of monthly percent returns, with each month's long-run average underneath \u2014 the standard way to look for seasonal patterns in gold and silver without eyeballing a price chart.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to analyse. ${FIXED_METAL_NAMES}`),
+    years: z3.number().int().min(5).max(58).default(20).describe("How many years of monthly returns to include in the grid.")
+  })
+});
+var metalVolatilityMeta = defineFrameMeta({
+  name: "metal-volatility",
+  label: "Metal Volatility",
+  category: "metals",
+  iconUrl: widgetIcon("metal-volatility"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "Rolling annualised realised volatility from daily fixes \u2014 how violent the metal has actually been, not what options imply. Quiet gold sits near 10%; a crisis takes it past 30%.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to analyse. ${FIXED_METAL_NAMES}`),
+    window: z3.number().int().min(20).max(365).default(90).describe(
+      "Rolling window in trading days. 30 is twitchy, 90 is the common standard, 252 is a year."
+    ),
+    years: yearsField(10, "How many years of the volatility series to chart.")
+  })
+});
+var goldSilverRatioMeta = defineFrameMeta({
+  name: "gold-silver-ratio",
+  label: "Gold/Silver Ratio",
+  category: "metals",
+  iconUrl: widgetIcon("gold-silver-ratio"),
+  layout: { w: 4, h: 3, minW: 3, minH: 2 },
+  description: "How many ounces of silver one ounce of gold buys \u2014 the oldest relative-value gauge in metals. Shows the live ratio, where it sits in its own historical range, and the trend.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    years: yearsField(
+      20,
+      "How many years of ratio history to chart and rank against."
+    ),
+    showPercentile: z3.boolean().default(true).describe(
+      "Show where today's ratio ranks within the charted window \u2014 100% means silver has never been cheaper against gold over that span."
+    )
+  })
+});
+var metalRatioChartMeta = defineFrameMeta({
+  name: "metal-ratio-chart",
+  label: "Metal Ratio Chart",
+  category: "metals",
+  iconUrl: widgetIcon("metal-ratio-chart"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "The price of any metal divided by any other, charted over time \u2014 gold/silver, gold/platinum, platinum/palladium. Relative value between two metals, free of the dollar's own trend.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    numerator: z3.enum(FIXED_METALS).default("XAU").describe(`Metal on top of the ratio. ${FIXED_METAL_NAMES}`),
+    denominator: z3.enum(FIXED_METALS).default("XAG").describe(
+      "Metal on the bottom of the ratio. Must differ from the numerator."
+    ),
+    years: yearsField(20, "How many years of ratio history to chart.")
+  })
+});
+var metalCompareChartMeta = defineFrameMeta({
+  name: "metal-compare-chart",
+  label: "Metal Compare",
+  category: "metals",
+  iconUrl: widgetIcon("metal-compare-chart"),
+  layout: { w: 6, h: 4, minW: 4, minH: 3 },
+  description: "Several metals rebased to 0% at the start of the window so a $4,000 gold and a $58 silver compare on one axis. The relative-performance race across the complex.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbols: z3.array(z3.enum(FIXED_METALS)).min(2).max(4).default([...FIXED_METALS]).describe(`Metals to race against each other. ${FIXED_METAL_NAMES}`),
+    years: yearsField(10, "How many years the race runs over.")
+  })
+});
+var metalPerformanceMeta = defineFrameMeta({
+  name: "metal-performance",
+  label: "Metal Performance",
+  category: "metals",
+  iconUrl: widgetIcon("metal-performance"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "One metal's return across standard horizons \u2014 1M, 3M, 6M, YTD, 1Y, 5Y, 10Y, 20Y \u2014 as diverging bars. Switch to annualised to compare long horizons honestly instead of letting a 20-year number dwarf everything.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to measure. ${FIXED_METAL_NAMES}`),
+    mode: z3.enum(["cumulative", "annualized"]).default("cumulative").describe(
+      "cumulative = total return over each horizon; annualized = the compound annual rate, which makes long and short horizons comparable."
+    )
+  })
+});
+var metalAthMeta = defineFrameMeta({
+  name: "metal-ath",
+  label: "Metal ATH Watch",
+  category: "metals",
+  iconUrl: widgetIcon("metal-ath"),
+  layout: { w: 3, h: 3, minW: 2, minH: 2 },
+  description: "All-time-high watch from the full fix history: the record price and when it was set, how far below it the metal trades now, and how long it has been since the last record.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to watch. ${FIXED_METAL_NAMES}`)
+  })
+});
+var metalFixTableMeta = defineFrameMeta({
+  name: "metal-fix-table",
+  label: "London Fix Table",
+  category: "metals",
+  iconUrl: widgetIcon("metal-fix-table"),
+  layout: { w: 3, h: 4, minW: 2, minH: 3 },
+  description: "The most recent daily London fixes as a table \u2014 date, fix price and the day-over-day change. The settlement prints themselves, for anyone who prices contracts off the fix rather than off spot.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal whose fixes to list. ${FIXED_METAL_NAMES}`),
+    currency: z3.enum(["USD", "GBP", "EUR"]).default("USD").describe(
+      "Which published fix SERIES to list \u2014 the LBMA publishes all three as separate prints, not conversions of one another. This is a data choice, not a display one: to change what the card renders money in, set the frame instance's own `currency` (sibling of `config`) or the dashboard's. A USD fix follows that display currency; a GBP/EUR fix is shown as published."
+    ),
+    rows: z3.number().int().min(5).max(40).default(12).describe("How many recent fixes to list, newest first.")
+  })
+});
+var metalMilestonesMeta = defineFrameMeta({
+  name: "metal-milestones",
+  label: "Metal Milestones",
+  category: "metals",
+  iconUrl: widgetIcon("metal-milestones"),
+  layout: { w: 3, h: 4, minW: 2, minH: 3 },
+  description: "When the metal first crossed each round-number price \u2014 $100, $500, $1,000, $2,000 \u2014 and how long each leg took. A timeline only decades of fix history can tell, and the most human way to read gold's long climb.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal whose milestones to list. ${FIXED_METAL_NAMES}`),
+    newestFirst: z3.boolean().default(true).describe(
+      "List the most recent milestone at the top. Turn off to read the climb chronologically from 1968."
+    )
+  })
+});
+var metalReturnDistributionMeta = defineFrameMeta({
+  name: "metal-return-distribution",
+  label: "Return Distribution",
+  category: "metals",
+  iconUrl: widgetIcon("metal-return-distribution"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "Histogram of the metal's periodic returns over decades, with the mean marked \u2014 how fat the tails really are, rather than the tidy bell curve risk models assume.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(`Metal to analyse. ${FIXED_METAL_NAMES}`),
+    period: z3.enum(["daily", "monthly"]).default("monthly").describe(
+      "Bucket returns by trading day or by calendar month. Monthly is smoother and easier to read; daily exposes the tails."
+    ),
+    years: yearsField(30, "How many years of returns to bucket.")
+  })
+});
+var metalsCorrelationMeta = defineFrameMeta({
+  name: "metals-correlation",
+  label: "Metals Correlation",
+  category: "metals",
+  iconUrl: widgetIcon("metals-correlation"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Correlation matrix of daily returns across gold, silver, platinum and palladium over a chosen window \u2014 which metals actually move together, and which only look like they do.",
+  capabilities: ["metal-history"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    years: yearsField(
+      3,
+      "Window, in years, the correlations are measured over."
+    )
+  })
+});
+var btcInGoldMeta = defineFrameMeta({
+  name: "btc-in-gold",
+  label: "BTC in Gold",
+  category: "metals",
+  iconUrl: widgetIcon("btc-in-gold"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "Bitcoin priced in ounces of gold instead of dollars \u2014 how many ounces one BTC buys, charted over time. The clean way to ask whether Bitcoin is beating the oldest hard asset or just the dollar.",
+  capabilities: ["metal-history", "price-history-daily"],
+  source: SOURCES.lbma,
+  schema: z3.object({
+    years: yearsField(
+      10,
+      "How many years of the BTC-in-ounces ratio to chart."
+    ),
+    logScale: z3.boolean().default(true).describe(
+      "Use a logarithmic axis \u2014 the ratio has spanned four orders of magnitude, so linear hides everything before the last cycle."
+    )
+  })
+});
+var metalCotNetMeta = defineFrameMeta({
+  name: "metal-cot-net",
+  label: "COT Net Positioning",
+  category: "metals",
+  iconUrl: widgetIcon("metal-cot-net"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "Net speculative positioning from the CFTC's weekly Commitments of Traders \u2014 non-commercial longs minus shorts, against a zero line. Crowded longs have marked local tops in gold for decades.",
+  capabilities: ["metal-positioning"],
+  source: SOURCES.cftc,
+  schema: z3.object({
+    symbol: z3.enum(METAL_SYMBOLS).default("XAU").describe(`Metal futures market to read. ${METAL_NAMES}.`),
+    years: z3.number().int().min(1).max(10).default(5).describe("How many years of weekly reports to chart."),
+    showOpenInterest: z3.boolean().default(false).describe(
+      "Overlay total open interest so a change in net positioning can be read against whether the whole market grew or shrank."
+    )
+  })
+});
+var metalCotBreakdownMeta = defineFrameMeta({
+  name: "metal-cot-breakdown",
+  label: "COT Trader Breakdown",
+  category: "metals",
+  iconUrl: widgetIcon("metal-cot-breakdown"),
+  layout: { w: 4, h: 3, minW: 3, minH: 2 },
+  description: "The latest COT week split by trader class \u2014 non-commercial speculators, commercial hedgers and small traders \u2014 as opposing long and short bars, plus each group's net and its week-over-week change.",
+  capabilities: ["metal-positioning"],
+  source: SOURCES.cftc,
+  schema: z3.object({
+    symbol: z3.enum(METAL_SYMBOLS).default("XAU").describe(`Metal futures market to read. ${METAL_NAMES}.`)
+  })
+});
+var metalCotGaugeMeta = defineFrameMeta({
+  name: "metal-cot-gauge",
+  label: "COT Positioning Gauge",
+  category: "metals",
+  iconUrl: widgetIcon("metal-cot-gauge"),
+  layout: { w: 3, h: 3, minW: 2, minH: 2 },
+  description: "Where speculative net positioning sits inside its own historical range, as a dial from washed-out short to crowded long \u2014 a contrarian sentiment gauge built from the CFTC's own weekly numbers.",
+  capabilities: ["metal-positioning"],
+  source: SOURCES.cftc,
+  schema: z3.object({
+    symbol: z3.enum(METAL_SYMBOLS).default("XAU").describe(`Metal futures market to read. ${METAL_NAMES}.`),
+    years: z3.number().int().min(1).max(10).default(5).describe("Lookback the percentile is ranked against, in years.")
+  })
+});
+var metalOpenInterestMeta = defineFrameMeta({
+  name: "metal-open-interest",
+  label: "Futures Open Interest",
+  category: "metals",
+  iconUrl: widgetIcon("metal-open-interest"),
+  layout: { w: 5, h: 4, minW: 4, minH: 3 },
+  description: "Total open interest in the metal's US futures contract, weekly from the CFTC \u2014 in contracts, in ounces, or in dollar notional at today's spot. How much paper claim sits on top of the physical market.",
+  capabilities: ["metal-positioning", "metal-spot"],
+  source: SOURCES.cftc,
+  schema: z3.object({
+    symbol: z3.enum(METAL_SYMBOLS).default("XAU").describe(`Metal futures market to read. ${METAL_NAMES}.`),
+    years: z3.number().int().min(1).max(10).default(5).describe("How many years of weekly open interest to chart."),
+    unit: z3.enum(["contracts", "ounces", "notional"]).default("contracts").describe(
+      "contracts = as CFTC reports it; ounces = contracts \xD7 contract size; notional = ounces \xD7 live spot (needs a spot quote)."
+    )
+  })
+});
+var metalPositioningVsPriceMeta = defineFrameMeta({
+  name: "metal-positioning-vs-price",
+  label: "Positioning vs Price",
+  category: "metals",
+  iconUrl: widgetIcon("metal-positioning-vs-price"),
+  layout: { w: 6, h: 4, minW: 4, minH: 3 },
+  description: "Net speculative positioning and the metal's price on one rebased chart, so you can see whether a rally is being led by the futures crowd or happening in spite of them \u2014 and where the two have diverged.",
+  capabilities: ["metal-positioning", "metal-history"],
+  source: SOURCES.cftc,
+  schema: z3.object({
+    symbol: z3.enum(FIXED_METALS).default("XAU").describe(
+      `Metal to compare. ${FIXED_METAL_NAMES} (the price leg needs an LBMA fix, so copper isn't available here).`
+    ),
+    years: z3.number().int().min(1).max(10).default(5).describe("How many years both series cover.")
+  })
+});
+var usGoldReserveMeta = defineFrameMeta({
+  name: "us-gold-reserve",
+  label: "US Gold Reserve",
+  category: "metals",
+  iconUrl: widgetIcon("us-gold-reserve"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "The U.S. Treasury's official gold holding from its own monthly status report: total fine ounces, the statutory book value that still carries it at $42.22/oz, and what the same metal is worth at today's spot. The gap between the two is the headline.",
+  capabilities: ["gold-reserve", "metal-spot"],
+  source: SOURCES.treasury,
+  schema: z3.object({
+    showMarketValue: z3.boolean().default(true).describe(
+      "Value the reserve at live spot alongside the statutory book value, and show the difference."
+    )
+  })
+});
+var usGoldVaultsMeta = defineFrameMeta({
+  name: "us-gold-vaults",
+  label: "US Gold Vaults",
+  category: "metals",
+  iconUrl: widgetIcon("us-gold-vaults"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Where the U.S. official gold physically sits \u2014 Fort Knox, West Point, Denver, the New York Fed vault and Mint working stock \u2014 sized by fine ounces, straight from the Treasury's monthly report.",
+  capabilities: ["gold-reserve"],
+  source: SOURCES.treasury,
+  schema: z3.object({
+    mode: z3.enum(["treemap", "bars"]).default("treemap").describe(
+      "treemap = area per vault, good for the size contrast; bars = ranked horizontal bars, easier to read exact ounces."
+    )
+  })
+});
+var tokenizedGoldMeta = defineFrameMeta({
+  name: "tokenized-gold",
+  label: "Tokenized Gold",
+  category: "metals",
+  iconUrl: widgetIcon("tokenized-gold"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Gold-backed tokens (PAXG, XAUT) with their premium or discount to physical spot, market cap and the ounces they claim to vault \u2014 the crypto wrapper on bullion, priced against the real thing.",
+  capabilities: ["tokenized-gold"],
+  source: SOURCES.coingecko,
+  schema: z3.object({
+    showPremium: z3.boolean().default(true).describe(
+      "Show each token's premium (+) or discount (\u2212) against live spot gold. A persistent premium is the market pricing convenience over custody."
+    )
+  })
+});
 var frameMetas = [
+  metalsBoardMeta,
+  metalPriceMeta,
+  metalValueMeta,
+  metalPriceChartMeta,
+  metalDrawdownMeta,
+  metalAnnualReturnsMeta,
+  metalSeasonalityMeta,
+  metalVolatilityMeta,
+  goldSilverRatioMeta,
+  metalRatioChartMeta,
+  metalCompareChartMeta,
+  metalPerformanceMeta,
+  metalAthMeta,
+  metalFixTableMeta,
+  metalMilestonesMeta,
+  metalReturnDistributionMeta,
+  metalsCorrelationMeta,
+  btcInGoldMeta,
+  metalCotNetMeta,
+  metalCotBreakdownMeta,
+  metalCotGaugeMeta,
+  metalOpenInterestMeta,
+  metalPositioningVsPriceMeta,
+  usGoldReserveMeta,
+  usGoldVaultsMeta,
+  tokenizedGoldMeta,
   customDataMeta,
   newsFeedMeta,
   portfolioValueMeta,
@@ -3657,6 +4172,7 @@ var frameMetas = [
   nftCollectionsMeta,
   dexHotPoolsMeta,
   chainActivityMeta,
+  orderBookDepthMeta,
   nftTreemapMeta,
   dexPoolTreemapMeta,
   sectorBarsMeta,
@@ -3886,6 +4402,7 @@ function skeleton(title, author) {
       upColor: "#3fd08f",
       downColor: "#ff6b81"
     },
+    currency: { code: "USD" },
     typography: {
       fontFamily: "sans",
       numericStyle: "proportional",