Parse official NAV/Index returns and distribution tax breakdown

The product page's own "Total Returns" table already carries NAV
Returns and Underlying Index Returns rows alongside the Market Price
Returns row this script parsed; both are now captured into meta.json
without touching the existing primary field. Its "Recent Distributions"
table (ex/record/payable date plus Ordinary Income/ST Cap Gains/LT Cap
Gains/Return of Capital/Total) is now the primary distributions source,
merged with Yahoo dividend events only for ex-dates the official table
doesn't cover; each row's origin stays visible via a source label.
Updated app.tsx subtitles that had become factually wrong once Yahoo
was no longer the sole source.

Author: daggerok

README.md

@@ -1,6 +1,6 @@
 # WisdomTree
 
-WisdomTree ETF holdings to Watchlist. A single-file client-side tool reading the generated `./api/wisdomtree` static feed (WisdomTree product pages, SEC EDGAR N-PORT-P holdings, Yahoo Finance history) into a searchable ETF/asset-class catalog with per-fund tabs, watchlist, N-PORT upload, CSV/TXT export — the same look, feel, columns and business logic as the sibling applications.
+WisdomTree ETF holdings to Watchlist. A single-file client-side tool reading the generated `./api/wisdomtree` static feed (WisdomTree product pages — including official Market Price/NAV/Underlying Index returns and the official tax-character distributions table, SEC EDGAR N-PORT-P holdings, Yahoo Finance history with a narrow distributions/returns fallback) into a searchable ETF/asset-class catalog with per-fund tabs, watchlist, N-PORT upload, CSV/TXT export — the same look, feel, columns and business logic as the sibling applications.
 
 ## Using Bun
 
@@ -31,7 +31,8 @@ The **Update WisdomTree ETF data** GitHub Actions workflow exposes the same sett
 | --- | --- |
 | Catalog (all US WisdomTree ETFs) | `https://www.wisdomtree.com/investments` (WisdomTree product table) |
 | Holdings per fund | SEC EDGAR N-PORT-P `primary_doc.xml` (WisdomTree Trust CIK 0001350487) |
-| Daily history, distributions | Yahoo Finance chart API for daily history |
+| Per-fund returns, distributions | WisdomTree product page's "Total Returns" table (Market Price/NAV/Underlying Index rows) and "Recent Distributions" table (ex/record/payable date + Ordinary Income/ST/LT Cap Gains/Return of Capital) — the primary source for both |
+| Daily history; returns/distributions fallback | Yahoo Finance chart API for daily history unconditionally, and as fallback for Market Price Returns tenors and distribution ex-dates the official page doesn't cover |
 | Fallback | WisdomTree product pages for NAV, expense ratio, yields |
 
 Each fund carries a derived `metrics` object that powers the catalog columns shared with the sibling sites:

app.tsx

@@ -1565,7 +1565,7 @@ function renderOverviewTable(fund: FundRow): void {
   }
 
   el.tickerCount.textContent = fund.ticker;
-  renderSubtitle(`${fund.ticker} overview · ${rows.length} metrics. Returns are derived from adjusted market-price closes, not official NAV returns.`);
+  renderSubtitle(`${fund.ticker} overview · ${rows.length} metrics. Headline returns use official Market Price Returns where WisdomTree publishes them, falling back to adjusted market-price closes; official NAV/Underlying Index returns are recorded separately in the data feed.`);
 }
 
 function renderDistributionsTable(fund: FundRow): void {
@@ -1601,7 +1601,7 @@ function renderDistributionsTable(fund: FundRow): void {
   }
 
   el.tickerCount.textContent = fund.ticker;
-  renderSubtitle(`${fund.ticker} distributions · dividend history from the Yahoo chart feed (ex-date, amount); frequency is inferred from the cadence.`);
+  renderSubtitle(`${fund.ticker} distributions · the official WisdomTree tax-character breakdown for recent ex-dates, with Yahoo dividend events (ex-date, amount only) filling in older ex-dates it doesn't cover; frequency is inferred from the cadence.`);
 }
 
 // =========================================================================

scripts/update-data.test.ts

@@ -5,6 +5,7 @@ import {
   annualizedToTotal,
   cleanHoldingTicker,
   inferDistributionFrequency,
+  mergeDistributionRecords,
   nportUrlFor,
   normalizeHoldingName,
   parseAumRange,
@@ -13,6 +14,7 @@ import {
   parseEdgarAtomFilings,
   parseFundTickerMap,
   parseNport,
+  parseOfficialDistributions,
   parseProductPageSummary,
   parseRange,
   priceReturns,
@@ -68,13 +70,110 @@ describe('WisdomTree catalog parser', () => {
 });
 
 describe('official WisdomTree product page parser', () => {
+  // Verified live against wisdomtree.com/us/products/fixed-income/usfr: the
+  // "Total Returns" table carries three rows per section, in this order —
+  // Underlying Index Returns, NAV Returns, Market Price Returns.
+  const page = `# USFR WisdomTree Floating Rate Treasury Fund\n\n### 3.68%\n\n30-day SEC yield\n\nAs of 9/15/2026\n\n| Product Overview | As of 9/16/2026 |\n| --- | --- |\n| Expense Ratio | 0.15% |\n| CUSIP | 97717Y527 |\n| Total Assets (000) | $19,560,180.26 |\n| SEC 30-day Yield | 3.68% |\n\n### Net Asset Value\n\n| Net Asset Value | As of 9/16/2026 |\n| --- | --- |\n| NAV | $50.476 |\n| Premium/Discount to NAV | 0.01% |\n\n### Closing Market Price\n\n| Closing Market Value | As of 9/15/2026 |\n| --- | --- |\n| Closing Market Price | $50.470 |\n\n### Total Returns\n\nMonth End Performance (8/31/2026)\n\n| Cumulative | 1 Month | 3 Month | YTD | Since Inception* | |\n| --- | --- | --- | --- | --- | --- |\n| Underlying Index Returns | 0.33% | 1.04% | 2.70% | 30.94% | |\n| NAV Returns | 0.32% | 1.00% | 2.57% | 28.21% | |\n| Market Price Returns | 0.32% | 1.02% | 2.59% | 28.05% | |\n| Average Annual | 1 Year | 3 Year | 5 Year | 10 Year | Since Inception* |\n| Underlying Index Returns | 4.18% | 4.84% | 4.04% | 2.67% | 2.17% |\n| NAV Returns | 3.98% | 4.66% | 3.86% | 2.49% | 2.00% |\n| Market Price Returns | 4.00% | 4.65% | 3.86% | 2.52% | 1.99% |\n\nQuarter End Performance (6/30/2026)\n\n| Cumulative | Since Inception* |  |  |  |  |\n| --- | --- | --- | --- | --- | --- |\n| Underlying Index Returns | 30.04% |  |  |  |  |\n| NAV Returns | 27.37% |  |  |  |  |\n| Market Price Returns | 27.19% |  |  |  |  |\n| Average Annual | 1 Year | 3 Year | 5 Year | 10 Year | Since Inception* |\n| Underlying Index Returns | 4.30% | 4.90% | 4.10% | 2.70% | 2.20% |\n| NAV Returns | 4.10% | 4.70% | 3.90% | 2.50% | 2.02% |\n| Market Price Returns | 4.12% | 4.69% | 3.90% | 2.53% | 2.01% |`;
+
   test('reads NAV, market price, SEC yield, CUSIP and month-end market-price returns', () => {
-    const page = `# USFR WisdomTree Floating Rate Treasury Fund\n\n### 3.68%\n\n30-day SEC yield\n\nAs of 9/15/2026\n\n| Product Overview | As of 9/16/2026 |\n| --- | --- |\n| Expense Ratio | 0.15% |\n| CUSIP | 97717Y527 |\n| Total Assets (000) | $19,560,180.26 |\n| SEC 30-day Yield | 3.68% |\n\n### Net Asset Value\n\n| Net Asset Value | As of 9/16/2026 |\n| --- | --- |\n| NAV | $50.476 |\n| Premium/Discount to NAV | 0.01% |\n\n### Closing Market Price\n\n| Closing Market Value | As of 9/15/2026 |\n| --- | --- |\n| Closing Market Price | $50.470 |\n\n### Total Returns\n\nMonth End Performance (8/31/2026)\n\n| Cumulative | 1 Month | 3 Month | YTD | Since Inception* | |\n| --- | --- | --- | --- | --- | --- |\n| Market Price Returns | 0.32% | 1.02% | 2.59% | 28.05% | |\n| Average Annual | 1 Year | 3 Year | 5 Year | 10 Year | Since Inception* |\n| Market Price Returns | 4.00% | 4.65% | 3.86% | 2.52% | 1.99% |`;
     const parsed = parseProductPageSummary(page);
     expect(parsed).toMatchObject({ name: 'WisdomTree Floating Rate Treasury Fund', cusip: '97717Y527', nav: 50.476, marketPrice: 50.47, premiumDiscount: 0.01, secYield: 3.68, totalAssets: 19560180260 });
     expect(parsed.navAsOfDate).toBe('2026-09-16');
     expect(parsed.officialReturns.monthEnd).toMatchObject({ asOfDate: '2026-08-31', ytd: 2.59, cagr3y: 4.65, siAnn: 1.99 });
   });
+
+  test('captures NAV Returns and Underlying Index Returns rows alongside Market Price Returns, without overwriting it', () => {
+    const parsed = parseProductPageSummary(page);
+    const monthEnd = parsed.officialReturns.monthEnd!;
+    // Market Price Returns (the primary row) is untouched.
+    expect(monthEnd).toMatchObject({ mo1: 0.32, qtd: 1.02, ytd: 2.59, yr1: 4.00, cagr3y: 4.65, cagr5y: 3.86, cagr10y: 2.52, siAnn: 1.99 });
+    // NAV Returns and Underlying Index Returns are distinct labeled rows.
+    expect(monthEnd.navReturns).toMatchObject({ mo1: 0.32, qtd: 1.00, ytd: 2.57, yr1: 3.98, cagr3y: 4.66, cagr5y: 3.86, cagr10y: 2.49, siAnn: 2.00 });
+    expect(monthEnd.indexReturns).toMatchObject({ mo1: 0.33, qtd: 1.04, ytd: 2.70, yr1: 4.18, cagr3y: 4.84, cagr5y: 4.04, cagr10y: 2.67, siAnn: 2.17 });
+  });
+
+  test('handles the Quarter End cumulative row, which the site renders with blank trailing cells', () => {
+    // Verified live against wisdomtree.com/us/products/fixed-income/usfr:
+    // the Quarter End "Cumulative" row only ever publishes Since Inception,
+    // leaving the 1-month/3-month/YTD cells blank. Pre-existing indexing
+    // (unchanged by this parser extension) reads that single value into the
+    // same cumulative-row slot Month End uses for its 1-month figure; the
+    // point of this test is that the blank cells parse cleanly to null on
+    // the new nav/index rows too, instead of throwing or becoming NaN.
+    const parsed = parseProductPageSummary(page);
+    const quarterEnd = parsed.officialReturns.quarterEnd!;
+    expect(quarterEnd.mo1).toBe(27.19);
+    expect(quarterEnd.qtd).toBeNull();
+    expect(quarterEnd.navReturns).toMatchObject({ mo1: 27.37, qtd: null, ytd: null, yr1: 4.10, cagr3y: 4.70, cagr5y: 3.90, cagr10y: 2.50, siAnn: 2.02 });
+    expect(quarterEnd.indexReturns).toMatchObject({ mo1: 30.04, qtd: null, ytd: null, yr1: 4.30, cagr3y: 4.90, cagr5y: 4.10, cagr10y: 2.70, siAnn: 2.20 });
+  });
+
+  test('leaves navReturns/indexReturns null when the table only publishes Market Price Returns', () => {
+    const marketOnly = `# GDE WisdomTree Efficient Gold Plus Equity Strategy Fund\n\n### Total Returns\n\nMonth End Performance (8/31/2026)\n\n| Cumulative | 1 Month | 3 Month | YTD | Since Inception* | |\n| --- | --- | --- | --- | --- | --- |\n| Market Price Returns | 1.00% | 2.00% | 3.00% | 4.00% | |`;
+    const parsed = parseProductPageSummary(marketOnly);
+    expect(parsed.officialReturns.monthEnd).toMatchObject({ mo1: 1.00, navReturns: null, indexReturns: null });
+  });
+});
+
+describe('official WisdomTree distributions parser', () => {
+  test('reads ex-date/record/payable dates and the full tax-character breakdown', () => {
+    // Verified live against wisdomtree.com/us/products/equity/dgrw.
+    const page = '### Recent Distributions\n\n| Ex-Dividend Date | Record Date | Payable Date | Ordinary Income | Short Term Capital Gains | Long Term Capital Gains | Return of Capital | Total Distribution |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| 9/25/2026 | 9/25/2026 | 9/29/2026 | $0.17000 | $0.00000 | $0.00000 | $0.00000 | $0.17000 |\n| 8/26/2026 | 8/26/2026 | 8/28/2026 | $0.05500 | $0.00000 | $0.00000 | $0.00000 | $0.05500 |\n\n### Thought Leadership\n\n| Name | Ticker |\n| --- | --- |\n| unrelated | table |';
+    const rows = parseOfficialDistributions(page);
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toEqual({ exDate: '2026-09-25', recordDate: '2026-09-25', payableDate: '2026-09-29', ordinaryIncome: 0.17, shortTermCapitalGains: 0, longTermCapitalGains: 0, returnOfCapital: 0, total: 0.17 });
+    expect(rows[1].exDate).toBe('2026-08-26');
+  });
+
+  test('tolerates missing/blank cells the site sometimes renders', () => {
+    const page = '### Recent Distributions\n\n| Ex-Dividend Date | Record Date | Payable Date | Ordinary Income | Short Term Capital Gains | Long Term Capital Gains | Return of Capital | Total Distribution |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| 3/25/2020 | 3/25/2020 | 3/27/2020 | $0.05000 |  |  |  | $0.05000 |\n| 12/24/2019 | 12/24/2019 | 12/26/2019 | — | — | — | — | — |';
+    const rows = parseOfficialDistributions(page);
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toMatchObject({ ordinaryIncome: 0.05, shortTermCapitalGains: null, longTermCapitalGains: null, returnOfCapital: null, total: 0.05 });
+    expect(rows[1]).toMatchObject({ ordinaryIncome: null, shortTermCapitalGains: null, longTermCapitalGains: null, returnOfCapital: null, total: null });
+  });
+
+  test('returns an empty list when the page has no Recent Distributions section', () => {
+    expect(parseOfficialDistributions('# GDE\n\n### Total Returns\n\nno distributions section here')).toEqual([]);
+  });
+});
+
+describe('official-first distributions merge (house policy: official wins, Yahoo fills only what it does not cover)', () => {
+  test('prefers the official row over an overlapping Yahoo dividend event', () => {
+    const official = parseOfficialDistributions('### Recent Distributions\n\n| Ex-Dividend Date | Record Date | Payable Date | Ordinary Income | Short Term Capital Gains | Long Term Capital Gains | Return of Capital | Total Distribution |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| 9/25/2026 | 9/25/2026 | 9/29/2026 | $0.17000 | $0.00000 | $0.00000 | $0.00000 | $0.17000 |');
+    const yahoo = [{ epoch: Date.UTC(2026, 8, 25) / 1000, amount: 0.169 }]; // Yahoo's own rounding for the same ex-date.
+    const { rows, yahooOnlyCount } = mergeDistributionRecords(official, yahoo);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ total: 0.17, ordinaryIncome: 0.17 });
+    expect(yahooOnlyCount).toBe(0);
+  });
+
+  test('falls back to Yahoo dividend events for older ex-dates the small official table does not cover', () => {
+    const official = parseOfficialDistributions('### Recent Distributions\n\n| Ex-Dividend Date | Record Date | Payable Date | Ordinary Income | Short Term Capital Gains | Long Term Capital Gains | Return of Capital | Total Distribution |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| 9/25/2026 | 9/25/2026 | 9/29/2026 | $0.17000 | $0.00000 | $0.00000 | $0.00000 | $0.17000 |');
+    const yahoo = [
+      { epoch: Date.UTC(2013, 5, 20) / 1000, amount: 0.05 }, // an old, pre-tax-breakdown-era ex-date the official table no longer shows.
+      { epoch: Date.UTC(2026, 8, 25) / 1000, amount: 0.169 },
+    ];
+    const { rows, yahooOnlyCount } = mergeDistributionRecords(official, yahoo);
+    expect(rows).toHaveLength(2);
+    expect(yahooOnlyCount).toBe(1);
+    expect(rows[0]).toMatchObject({ exDate: '2013-06-20', total: 0.05, ordinaryIncome: null });
+    expect(rows[1]).toMatchObject({ exDate: '2026-09-25', total: 0.17 });
+  });
+
+  test('is exercised end-to-end as the fallback path for a fund whose official page has no distributions table at all', () => {
+    // Simulates a fund where productPageMarkdown fetched fine but carries no
+    // Recent Distributions section (or the product-page fetch failed
+    // entirely) — the same shape update-data.ts builds when
+    // parseOfficialDistributions([]) short-circuits to [].
+    const official = parseOfficialDistributions('# Some Fund\n\nno distributions section here');
+    expect(official).toEqual([]);
+    const yahoo = [{ epoch: Date.UTC(2026, 5, 25) / 1000, amount: 0.16 }, { epoch: Date.UTC(2026, 6, 28) / 1000, amount: 0.065 }];
+    const { rows, yahooOnlyCount } = mergeDistributionRecords(official, yahoo);
+    expect(yahooOnlyCount).toBe(2);
+    expect(rows.map((row) => row.total)).toEqual([0.16, 0.065]);
+    expect(rows.every((row) => row.ordinaryIncome === null)).toBe(true);
+  });
 });
 
 describe('SEC mapping and N-PORT', () => {