From e4b1537f2994ba003ee719df211068eed372e0c1 Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 22:53:08 -0600
Subject: [PATCH 1/9] test charts catalog content contracts

---
 tests/charts-catalog-assets.test.ts          |  90 ++++++++++++
 tests/charts-catalog-frame-embedding.test.ts |  67 +++++++++
 tests/charts-catalog-manifest.test.ts        | 140 +++++++++++++++++++
 tests/charts-catalog-raw-content.test.ts     |  41 ++++++
 tests/charts-catalog-search.test.ts          |  40 ++++++
 tests/charts-catalog-site-contracts.test.ts  |  58 ++++++++
 tests/charts-catalog-test-fixture.ts         | 111 +++++++++++++++
 7 files changed, 547 insertions(+)
 create mode 100644 tests/charts-catalog-assets.test.ts
 create mode 100644 tests/charts-catalog-frame-embedding.test.ts
 create mode 100644 tests/charts-catalog-manifest.test.ts
 create mode 100644 tests/charts-catalog-raw-content.test.ts
 create mode 100644 tests/charts-catalog-search.test.ts
 create mode 100644 tests/charts-catalog-site-contracts.test.ts
 create mode 100644 tests/charts-catalog-test-fixture.ts

diff --git a/tests/charts-catalog-assets.test.ts b/tests/charts-catalog-assets.test.ts
new file mode 100644
index 000000000..0a8882037
--- /dev/null
+++ b/tests/charts-catalog-assets.test.ts
@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import {
+  getChartsCatalogAssetHeaders,
+  parseChartsCatalogAssetRequest,
+} from '../src/utils/charts-catalog-assets'
+import {
+  getChartsCatalogAssetUrl,
+  parseChartsCatalogManifest,
+} from '../src/utils/charts-catalog'
+import {
+  artifactRevision,
+  createChartsCatalogManifest,
+  tanstackAsset,
+} from './charts-catalog-test-fixture'
+
+const manifest = parseChartsCatalogManifest(createChartsCatalogManifest())
+
+test('catalog assets resolve only through an immutable artifact revision', () => {
+  const request = parseChartsCatalogAssetRequest({
+    artifactRevision,
+    assetPath: tanstackAsset,
+    manifest,
+  })
+
+  assert.equal(request.repo, 'tanstack/charts')
+  assert.equal(request.repoPath, tanstackAsset)
+  assert.equal(
+    getChartsCatalogAssetUrl(artifactRevision, tanstackAsset),
+    `/charts/catalog/assets/${artifactRevision}/${tanstackAsset}`,
+  )
+})
+
+for (const artifactRevision of [
+  'catalog-dist',
+  'main',
+  'A'.repeat(40),
+  '1'.repeat(39),
+  '1'.repeat(41),
+]) {
+  test(`catalog assets reject mutable or malformed revision ${artifactRevision}`, () => {
+    assert.throws(() =>
+      parseChartsCatalogAssetRequest({
+        artifactRevision,
+        assetPath: tanstackAsset,
+        manifest,
+      }),
+    )
+  })
+}
+
+for (const assetPath of [
+  '../catalog.json',
+  'assets/../catalog.json',
+  'assets/%2e%2e/catalog.json',
+  'assets/%2Fcatalog.json',
+  'assets/%5ccatalog.json',
+  'assets\\catalog.js',
+  '/assets/tanstack-AbC_1.js',
+  'assets//tanstack-AbC_1.js',
+  'assets/not-allowlisted.js',
+  'catalog.json',
+]) {
+  test(`catalog assets reject unsafe or unlisted path ${assetPath}`, () => {
+    assert.throws(() =>
+      parseChartsCatalogAssetRequest({
+        artifactRevision,
+        assetPath,
+        manifest,
+      }),
+    )
+  })
+}
+
+test('catalog JavaScript uses immutable same-origin response headers', () => {
+  const headers = new Headers(getChartsCatalogAssetHeaders())
+
+  assert.equal(
+    headers.get('Cache-Control'),
+    'public, max-age=31536000, immutable',
+  )
+  assert.equal(
+    headers.get('Cloudflare-CDN-Cache-Control'),
+    'public, max-age=31536000, immutable',
+  )
+  assert.match(headers.get('Content-Type') ?? '', /javascript/)
+  assert.equal(headers.get('Cross-Origin-Resource-Policy'), 'same-origin')
+  assert.equal(headers.get('X-Content-Type-Options'), 'nosniff')
+  assert.equal(headers.get('Access-Control-Allow-Origin'), null)
+})
diff --git a/tests/charts-catalog-frame-embedding.test.ts b/tests/charts-catalog-frame-embedding.test.ts
new file mode 100644
index 000000000..7fde9277d
--- /dev/null
+++ b/tests/charts-catalog-frame-embedding.test.ts
@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import {
+  isChartsCatalogEmbedPath,
+  parseChartsCatalogEmbed,
+} from '../src/utils/charts-catalog-embed'
+import { isFrameEmbeddingAllowed } from '../src/utils/frame-embedding'
+
+test('only exact catalog embed documents bypass the global frame denial', () => {
+  assert.equal(isFrameEmbeddingAllowed('/charts/catalog/embed/01-line/'), true)
+  assert.equal(isFrameEmbeddingAllowed('/stats/npm/embed'), true)
+
+  for (const pathname of [
+    '/charts/catalog/',
+    '/charts/catalog/charts/01-line/',
+    '/charts/catalog/embed/',
+    '/charts/catalog/embed/01-line',
+    '/charts/catalog/embed/01-line/source/',
+    '/charts/catalog/embed-malicious/01-line/',
+    '/charts/catalog/embed/../admin/',
+    '/charts/catalog/embed/%2e%2e/',
+    '/charts/catalog/embed/01_line/',
+    '/charts/catalog/embed/01-line/?compare=1',
+  ]) {
+    assert.equal(
+      isFrameEmbeddingAllowed(pathname),
+      false,
+      `${pathname} must retain frame denial`,
+    )
+  }
+})
+
+test('catalog embed source validation is same-origin and parameter bounded', () => {
+  assert.deepEqual(
+    parseChartsCatalogEmbed(
+      'https://tanstack.com/charts/catalog/embed/01-line/?theme=dark&height=420&revision=2',
+    ),
+    {
+      caseId: '01-line',
+      origin: 'https://tanstack.com',
+    },
+  )
+
+  for (const source of [
+    'http://tanstack.com/charts/catalog/embed/01-line/',
+    'https://charts.tanstack.com/charts/catalog/embed/01-line/',
+    'https://tanstack.com:444/charts/catalog/embed/01-line/',
+    'https://tanstack.com/charts/catalog/embed/01-line/?compare=1',
+    'https://tanstack.com/charts/catalog/embed/01-line/?height=119',
+    'https://tanstack.com/charts/catalog/embed/01-line/?revision=10001',
+    'https://tanstack.com/charts/catalog/embed/01-line/#fragment',
+  ]) {
+    assert.equal(parseChartsCatalogEmbed(source), null, source)
+  }
+})
+
+test('embed path validation uses the producer case-id grammar', () => {
+  assert.equal(isChartsCatalogEmbedPath('/charts/catalog/embed/01-line/'), true)
+  assert.equal(
+    isChartsCatalogEmbedPath('/charts/catalog/embed/01_line/'),
+    false,
+  )
+  assert.equal(
+    isChartsCatalogEmbedPath('/charts/catalog/embed/01.line/'),
+    false,
+  )
+})
diff --git a/tests/charts-catalog-manifest.test.ts b/tests/charts-catalog-manifest.test.ts
new file mode 100644
index 000000000..802543d40
--- /dev/null
+++ b/tests/charts-catalog-manifest.test.ts
@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { parseChartsCatalogManifest } from '../src/utils/charts-catalog'
+import {
+  comparisonAsset,
+  createChartsCatalogManifest,
+  sharedAsset,
+  sourceRevision,
+  tanstackAsset,
+} from './charts-catalog-test-fixture'
+
+function expectRejected(
+  label: string,
+  mutate: (manifest: Record<string, any>) => void,
+) {
+  test(`catalog manifest rejects ${label}`, () => {
+    const manifest = createChartsCatalogManifest()
+    mutate(manifest)
+    assert.throws(() => parseChartsCatalogManifest(manifest))
+  })
+}
+
+test('catalog manifest accepts the generated v2 contract', () => {
+  const manifest = parseChartsCatalogManifest(createChartsCatalogManifest())
+
+  assert.equal(manifest.schemaVersion, 2)
+  assert.equal(manifest.revision, sourceRevision)
+  assert.equal(manifest.cases[0]?.id, '01-line')
+  assert.equal(manifest.cases[0]?.modules.tanstack.path, tanstackAsset)
+  assert.deepEqual(Object.keys(manifest.assets).sort(), [
+    comparisonAsset,
+    sharedAsset,
+    tanstackAsset,
+  ])
+})
+
+expectRejected('an unsupported schema version', (manifest) => {
+  manifest.schemaVersion = 1
+})
+
+expectRejected('a mutable or malformed source revision', (manifest) => {
+  manifest.revision = 'main'
+  manifest.source.ref = 'main'
+})
+
+expectRejected('an untrusted source repository', (manifest) => {
+  manifest.source.repo = 'someone/charts'
+})
+
+expectRejected('a source ref that differs from its revision', (manifest) => {
+  manifest.source.ref = '2'.repeat(40)
+})
+
+expectRejected('a different runtime export', (manifest) => {
+  manifest.runtime.export = 'default'
+})
+
+expectRejected('a different site origin', (manifest) => {
+  manifest.site.origin = 'https://example.com'
+})
+
+expectRejected('an altered embed protocol', (manifest) => {
+  manifest.embed.protocol.version = 2
+})
+
+expectRejected('asset traversal', (manifest) => {
+  manifest.assets['assets/../catalog.json'] = manifest.assets[tanstackAsset]
+  delete manifest.assets[tanstackAsset]
+  manifest.cases[0].modules.tanstack.path = 'assets/../catalog.json'
+})
+
+expectRejected('an asset with a malformed digest', (manifest) => {
+  manifest.assets[tanstackAsset].sha256 = 'not-a-sha256'
+})
+
+expectRejected('an import outside the asset allowlist', (manifest) => {
+  manifest.assets[tanstackAsset].imports = ['assets/missing-AbC_4.js']
+})
+
+expectRejected('a case module outside the asset allowlist', (manifest) => {
+  manifest.cases[0].modules.tanstack.path = 'assets/missing-AbC_4.js'
+})
+
+expectRejected('an invalid static preload closure', (manifest) => {
+  manifest.cases[0].modules.tanstack.preload = []
+})
+
+expectRejected('a non-debug comparison module', (manifest) => {
+  manifest.cases[0].modules.comparison.visibility = 'public'
+})
+
+expectRejected('source-code traversal', (manifest) => {
+  manifest.cases[0].code.tanstack = '../private.ts'
+})
+
+expectRejected('duplicate case ids', (manifest) => {
+  manifest.cases.push(structuredClone(manifest.cases[0]))
+})
+
+expectRejected('a case id outside the producer format', (manifest) => {
+  manifest.cases[0].id = '01_line'
+  manifest.cases[0].routes = {
+    page: '/charts/catalog/charts/01_line/',
+    embed: '/charts/catalog/embed/01_line/',
+  }
+})
+
+expectRejected('a TanStack source path for another case', (manifest) => {
+  manifest.cases[0].code.tanstack =
+    'benchmarks/conformance/cases/02-area/tanstack.ts'
+})
+
+expectRejected('a source path that disagrees with its renderer', (manifest) => {
+  manifest.cases[0].code.reference =
+    'benchmarks/conformance/cases/01-line/recharts.ts'
+})
+
+expectRejected(
+  'a comparison renderer that disagrees with metadata',
+  (manifest) => {
+    manifest.cases[0].modules.comparison.renderer = 'recharts'
+  },
+)
+
+expectRejected('a missing debug comparison module', (manifest) => {
+  delete manifest.cases[0].modules.comparison
+})
+
+expectRejected('an asset larger than the producer limit', (manifest) => {
+  manifest.assets[tanstackAsset].bytes = 1024 * 1024 + 1
+})
+
+expectRejected('an asset outside every implementation closure', (manifest) => {
+  manifest.assets['assets/orphan-AbC_4.js'] = {
+    bytes: 1,
+    sha256: 'd'.repeat(64),
+    imports: [],
+    dynamicImports: [],
+  }
+})
diff --git a/tests/charts-catalog-raw-content.test.ts b/tests/charts-catalog-raw-content.test.ts
new file mode 100644
index 000000000..aa4ddacc8
--- /dev/null
+++ b/tests/charts-catalog-raw-content.test.ts
@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { fetchRepoFile, fetchRepoRawFile } from '../src/utils/documents.server'
+import { resetGitHubContentCacheForTest } from '../src/utils/github-content-cache.server'
+
+test('raw GitHub content remains byte-for-byte text-equivalent', async () => {
+  resetGitHubContentCacheForTest()
+
+  const originalFetch = globalThis.fetch
+  const revision = '3'.repeat(40)
+  const path = 'assets/raw-contract-AbC_1.js'
+  const source = `const marker = "![chart](https://raw.githubusercontent.com/tanstack/charts/main/chart.svg)"\n`
+  let requestUrl = ''
+  let originCalls = 0
+
+  globalThis.fetch = async (input) => {
+    originCalls += 1
+    requestUrl = String(input)
+    return new Response(source, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+      },
+    })
+  }
+
+  try {
+    const transformed = await fetchRepoFile('tanstack/charts', revision, path)
+    assert.notEqual(transformed, source)
+
+    const result = await fetchRepoRawFile('tanstack/charts', revision, path)
+
+    assert.equal(result, source)
+    assert.equal(originCalls, 2)
+    assert.equal(
+      requestUrl,
+      `https://raw.githubusercontent.com/tanstack/charts/${revision}/${path}`,
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
diff --git a/tests/charts-catalog-search.test.ts b/tests/charts-catalog-search.test.ts
new file mode 100644
index 000000000..8edf20aa6
--- /dev/null
+++ b/tests/charts-catalog-search.test.ts
@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { parseChartsCatalogSearch } from '../src/utils/charts-catalog'
+
+test('catalog comparison mode requires one exact compare=1 parameter', () => {
+  for (const search of ['?compare=1', 'compare=1', '?view=all&compare=1']) {
+    assert.equal(
+      parseChartsCatalogSearch(search).comparison,
+      true,
+      `${search} should enable comparison mode`,
+    )
+  }
+
+  for (const search of [
+    '',
+    '?',
+    '?compare',
+    '?compare=',
+    '?compare=0',
+    '?compare=true',
+    '?compare=01',
+    '?Compare=1',
+    '?compare=1&compare=1',
+    '?compare=0&compare=1',
+    '?compare=1&compare=0',
+  ]) {
+    assert.equal(
+      parseChartsCatalogSearch(search).comparison,
+      false,
+      `${search || '(empty)'} should keep comparisons disabled`,
+    )
+  }
+})
+
+test('catalog embeds never enable comparison modules', () => {
+  assert.equal(
+    parseChartsCatalogSearch('?compare=1', { embed: true }).comparison,
+    false,
+  )
+})
diff --git a/tests/charts-catalog-site-contracts.test.ts b/tests/charts-catalog-site-contracts.test.ts
new file mode 100644
index 000000000..9ea4de85e
--- /dev/null
+++ b/tests/charts-catalog-site-contracts.test.ts
@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import {
+  chartsCatalogPublicationCacheTag,
+  getChartsCatalogSitemapEntries,
+  parseChartsCatalogManifest,
+} from '../src/utils/charts-catalog'
+import {
+  docsWebhookSources,
+  isWatchedDocsWebhookSource,
+  type DocsWebhookSource,
+} from '../src/utils/docs-webhook-sources'
+import { createChartsCatalogManifest } from './charts-catalog-test-fixture'
+
+test('sitemap exposes catalog discovery routes but not executable resources', () => {
+  const manifest = parseChartsCatalogManifest(createChartsCatalogManifest())
+  const entries = getChartsCatalogSitemapEntries(manifest)
+  const paths = entries.map((entry) => entry.path)
+
+  assert.deepEqual(paths, [
+    '/charts/catalog/',
+    '/charts/catalog/all/',
+    '/charts/catalog/charts/01-line/',
+  ])
+  assert.equal(
+    paths.some((path) => path.includes('/embed/')),
+    false,
+  )
+  assert.equal(
+    paths.some((path) => path.includes('/assets/')),
+    false,
+  )
+  assert.equal(
+    paths.some((path) => path.includes('?compare=1')),
+    false,
+  )
+})
+
+test('catalog publication pushes invalidate the GitHub content pipeline', () => {
+  assert.equal(
+    chartsCatalogPublicationCacheTag,
+    'charts-catalog:tanstack/charts:catalog-dist',
+  )
+  assert.equal(
+    isWatchedDocsWebhookSource('tanstack/charts', 'catalog-dist'),
+    true,
+  )
+  assert.equal(
+    isWatchedDocsWebhookSource('tanstack/charts', 'catalog-dist-other'),
+    false,
+  )
+
+  const chartsSource = (docsWebhookSources as Array<DocsWebhookSource>).find(
+    (source) => source.repo === 'tanstack/charts',
+  )
+  assert.ok(chartsSource)
+  assert.ok(chartsSource.refs.includes('catalog-dist'))
+})
diff --git a/tests/charts-catalog-test-fixture.ts b/tests/charts-catalog-test-fixture.ts
new file mode 100644
index 000000000..df2da1e37
--- /dev/null
+++ b/tests/charts-catalog-test-fixture.ts
@@ -0,0 +1,111 @@
+export const sourceRevision = '1'.repeat(40)
+export const artifactRevision = '2'.repeat(40)
+export const tanstackAsset = 'assets/tanstack-AbC_1.js'
+export const sharedAsset = 'assets/shared-XyZ_2.js'
+export const comparisonAsset = 'assets/plot-QrS_3.js'
+
+export function createChartsCatalogManifest(): Record<string, any> {
+  return {
+    schemaVersion: 2,
+    revision: sourceRevision,
+    source: {
+      repo: 'tanstack/charts',
+      ref: sourceRevision,
+    },
+    runtime: {
+      contractVersion: 1,
+      export: 'mount',
+    },
+    site: {
+      origin: 'https://tanstack.com',
+      basePath: '/charts/catalog/',
+      assetBasePath: '/charts/catalog/assets/',
+    },
+    embed: {
+      protocol: {
+        type: 'tanstack-charts:embed',
+        version: 1,
+        statuses: ['ready', 'resize', 'error'],
+        commands: ['set-theme'],
+      },
+      parameters: {
+        theme: {
+          values: ['system', 'light', 'dark'],
+          default: 'system',
+        },
+        height: {
+          minimum: 120,
+          maximum: 1_200,
+          default: 360,
+        },
+        revision: {
+          minimum: 0,
+          maximum: 10_000,
+          default: 0,
+        },
+      },
+    },
+    assets: {
+      [tanstackAsset]: {
+        bytes: 21,
+        sha256: 'a'.repeat(64),
+        imports: [sharedAsset],
+        dynamicImports: [],
+      },
+      [sharedAsset]: {
+        bytes: 13,
+        sha256: 'b'.repeat(64),
+        imports: [],
+        dynamicImports: [],
+      },
+      [comparisonAsset]: {
+        bytes: 17,
+        sha256: 'c'.repeat(64),
+        imports: [],
+        dynamicImports: [],
+      },
+    },
+    cases: [
+      {
+        schemaVersion: 1,
+        referenceRenderer: 'observable-plot',
+        order: 10,
+        id: '01-line',
+        title: 'Line',
+        family: 'cartesian',
+        intent: 'Show a line.',
+        support: 'native',
+        features: [],
+        geometry: [],
+        source: {
+          title: 'Observable Plot line',
+          url: 'https://observablehq.com/plot/marks/line',
+        },
+        ai: {
+          create: 'Create a line.',
+          maintain: 'Keep the line stable.',
+        },
+        routes: {
+          page: '/charts/catalog/charts/01-line/',
+          embed: '/charts/catalog/embed/01-line/',
+        },
+        code: {
+          tanstack: 'benchmarks/conformance/cases/01-line/tanstack.ts',
+          reference: 'benchmarks/conformance/cases/01-line/plot.ts',
+        },
+        modules: {
+          tanstack: {
+            path: tanstackAsset,
+            preload: [sharedAsset],
+          },
+          comparison: {
+            renderer: 'observable-plot',
+            path: comparisonAsset,
+            preload: [],
+            visibility: 'debug',
+          },
+        },
+      },
+    ],
+  }
+}

From 0aa5b9a53044455cf9a6598ccce6f5681c4f353f Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 22:58:09 -0600
Subject: [PATCH 2/9] Add native Charts catalog content pipeline

---
 src/components/charts/ChartsCatalogChart.tsx  | 191 ++++++++
 src/components/charts/ChartsCatalogEmbed.tsx  | 121 +++++
 src/components/charts/ChartsCatalogPages.tsx  | 384 +++++++++++++++
 src/routeTree.gen.ts                          | 160 ++++++
 src/routes/api/github/webhook.ts              |   4 +
 src/routes/charts.catalog.all.tsx             |  29 ++
 src/routes/charts.catalog.charts.$caseId.tsx  |  37 ++
 src/routes/charts.catalog.index.tsx           |  20 +
 src/routes/charts.catalog.tsx                 |  54 +++
 ...rts.catalog_.assets.$artifactRevision.$.ts |  53 ++
 src/routes/charts.catalog_.catalog[.]json.ts  |  24 +
 src/routes/charts.catalog_.embed.$caseId.tsx  | 163 +++++++
 src/server.ts                                 |   3 +-
 src/styles/app.css                            |  18 +
 src/utils/charts-catalog-assets.ts            |  41 ++
 src/utils/charts-catalog-embed.ts             |  80 +++
 src/utils/charts-catalog.functions.ts         | 157 ++++++
 src/utils/charts-catalog.server.ts            | 131 +++++
 src/utils/charts-catalog.ts                   | 454 ++++++++++++++++++
 src/utils/docs-webhook-sources.ts             |   5 +
 src/utils/documents.server.ts                 | 135 ++++++
 src/utils/frame-embedding.ts                  |   7 +
 src/utils/sitemap.ts                          |  23 +-
 23 files changed, 2290 insertions(+), 4 deletions(-)
 create mode 100644 src/components/charts/ChartsCatalogChart.tsx
 create mode 100644 src/components/charts/ChartsCatalogEmbed.tsx
 create mode 100644 src/components/charts/ChartsCatalogPages.tsx
 create mode 100644 src/routes/charts.catalog.all.tsx
 create mode 100644 src/routes/charts.catalog.charts.$caseId.tsx
 create mode 100644 src/routes/charts.catalog.index.tsx
 create mode 100644 src/routes/charts.catalog.tsx
 create mode 100644 src/routes/charts.catalog_.assets.$artifactRevision.$.ts
 create mode 100644 src/routes/charts.catalog_.catalog[.]json.ts
 create mode 100644 src/routes/charts.catalog_.embed.$caseId.tsx
 create mode 100644 src/utils/charts-catalog-assets.ts
 create mode 100644 src/utils/charts-catalog-embed.ts
 create mode 100644 src/utils/charts-catalog.functions.ts
 create mode 100644 src/utils/charts-catalog.server.ts
 create mode 100644 src/utils/charts-catalog.ts
 create mode 100644 src/utils/frame-embedding.ts

diff --git a/src/components/charts/ChartsCatalogChart.tsx b/src/components/charts/ChartsCatalogChart.tsx
new file mode 100644
index 000000000..400e335bd
--- /dev/null
+++ b/src/components/charts/ChartsCatalogChart.tsx
@@ -0,0 +1,191 @@
+import * as React from 'react'
+import { getChartsCatalogAssetUrl } from '~/utils/charts-catalog'
+
+export type ChartsCatalogModuleReference = {
+  path: string
+  preload: Array<string>
+}
+
+type ChartMountInput = {
+  width: number
+  height: number
+  revision: number
+  interactive?: boolean
+}
+
+type ChartMountHandle = {
+  update(input: ChartMountInput): void
+  destroy(): void
+}
+
+type ChartRuntimeModule = {
+  mount(container: HTMLElement, input: ChartMountInput): ChartMountHandle
+}
+
+export function ChartsCatalogChart({
+  artifactRevision,
+  caseId,
+  defer = false,
+  height = 360,
+  interactive = true,
+  module,
+  onStatus,
+  revision = 0,
+}: {
+  artifactRevision: string
+  caseId: string
+  defer?: boolean
+  height?: number
+  interactive?: boolean
+  module: ChartsCatalogModuleReference
+  onStatus?: (status: 'ready' | 'resize' | 'error') => void
+  revision?: number
+}) {
+  const containerRef = React.useRef<HTMLDivElement>(null)
+  const [visible, setVisible] = React.useState(!defer)
+  const [failed, setFailed] = React.useState(false)
+
+  React.useEffect(() => {
+    const container = containerRef.current
+    if (!defer || visible || !container) return
+
+    if (!('IntersectionObserver' in window)) {
+      setVisible(true)
+      return
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return
+        setVisible(true)
+        observer.disconnect()
+      },
+      { rootMargin: '480px 0px' },
+    )
+    observer.observe(container)
+    return () => observer.disconnect()
+  }, [defer, visible])
+
+  React.useEffect(() => {
+    const container = containerRef.current
+    if (!container || !visible) return
+
+    let cancelled = false
+    let handle: ChartMountHandle | undefined
+    let width = measureWidth(container)
+    const preloadLinks = module.preload.map((assetPath) => {
+      const link = document.createElement('link')
+      link.rel = 'modulepreload'
+      link.href = getChartsCatalogAssetUrl(artifactRevision, assetPath)
+      document.head.appendChild(link)
+      return link
+    })
+
+    setFailed(false)
+
+    void import(
+      /* @vite-ignore */
+      getChartsCatalogAssetUrl(artifactRevision, module.path)
+    )
+      .then((loaded: unknown) => {
+        if (cancelled) return
+        if (!isChartRuntimeModule(loaded)) {
+          throw new TypeError('Invalid Charts catalog runtime module')
+        }
+
+        const mounted = loaded.mount(container, {
+          width,
+          height,
+          revision,
+          interactive,
+        })
+        if (!isChartMountHandle(mounted)) {
+          throw new TypeError('Invalid Charts catalog mount handle')
+        }
+        handle = mounted
+        requestAnimationFrame(() => onStatus?.('ready'))
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return
+        console.error(`Unable to mount Charts catalog case ${caseId}`, error)
+        setFailed(true)
+        onStatus?.('error')
+      })
+
+    const resizeObserver = new ResizeObserver(() => {
+      const nextWidth = measureWidth(container)
+      if (nextWidth === width || nextWidth < 1) return
+      width = nextWidth
+      handle?.update({
+        width,
+        height,
+        revision,
+        interactive,
+      })
+      onStatus?.('resize')
+    })
+    resizeObserver.observe(container)
+
+    return () => {
+      cancelled = true
+      resizeObserver.disconnect()
+      handle?.destroy()
+      for (const link of preloadLinks) link.remove()
+      container.replaceChildren()
+    }
+  }, [
+    artifactRevision,
+    caseId,
+    height,
+    interactive,
+    module,
+    onStatus,
+    revision,
+    visible,
+  ])
+
+  return (
+    <div
+      className="charts-catalog-chart relative w-full overflow-visible"
+      data-chart-case={caseId}
+      style={{ minHeight: height }}
+    >
+      <div ref={containerRef} className="h-full w-full" />
+      {!visible || failed ? (
+        <div
+          className={`absolute inset-0 rounded-lg ${
+            failed
+              ? 'grid place-items-center text-sm text-red-700 dark:text-red-300'
+              : 'animate-pulse bg-gray-100 dark:bg-gray-900'
+          }`}
+        >
+          {failed ? 'Render failed' : null}
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+function measureWidth(container: HTMLElement) {
+  return Math.max(1, Math.floor(container.getBoundingClientRect().width))
+}
+
+function isChartRuntimeModule(value: unknown): value is ChartRuntimeModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'mount' in value &&
+    typeof value.mount === 'function'
+  )
+}
+
+function isChartMountHandle(value: unknown): value is ChartMountHandle {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'update' in value &&
+    typeof value.update === 'function' &&
+    'destroy' in value &&
+    typeof value.destroy === 'function'
+  )
+}
diff --git a/src/components/charts/ChartsCatalogEmbed.tsx b/src/components/charts/ChartsCatalogEmbed.tsx
new file mode 100644
index 000000000..68f215e7f
--- /dev/null
+++ b/src/components/charts/ChartsCatalogEmbed.tsx
@@ -0,0 +1,121 @@
+import * as React from 'react'
+import { useTheme } from '~/components/ThemeProvider'
+import { parseChartsCatalogEmbed } from '~/utils/charts-catalog-embed'
+
+type ChartsCatalogEmbedProps = Omit<
+  React.IframeHTMLAttributes<HTMLIFrameElement>,
+  'src'
+> & {
+  deferUntilVisible?: boolean
+  src: string
+  theme?: 'dark' | 'light' | 'system'
+}
+
+export function ChartsCatalogEmbed({
+  className,
+  deferUntilVisible = false,
+  loading = 'lazy',
+  onLoad,
+  src,
+  theme = 'system',
+  title,
+  ...iframeProps
+}: ChartsCatalogEmbedProps) {
+  const { resolvedTheme } = useTheme()
+  const frameRef = React.useRef<HTMLIFrameElement>(null)
+  const [shouldLoad, setShouldLoad] = React.useState(!deferUntilVisible)
+  const chartEmbed = React.useMemo(() => parseChartsCatalogEmbed(src), [src])
+  const iframeTitle = title?.trim() || 'TanStack Charts example'
+  const resolvedEmbedTheme = theme === 'system' ? resolvedTheme : theme
+
+  React.useEffect(() => {
+    const frame = frameRef.current
+    if (!deferUntilVisible || shouldLoad || !frame) return
+
+    if (!('IntersectionObserver' in window)) {
+      setShouldLoad(true)
+      return
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return
+        setShouldLoad(true)
+        observer.disconnect()
+      },
+      { rootMargin: '480px 0px' },
+    )
+    observer.observe(frame)
+    return () => observer.disconnect()
+  }, [deferUntilVisible, shouldLoad])
+
+  const postChartTheme = React.useCallback(() => {
+    const target = frameRef.current?.contentWindow
+    if (!chartEmbed || !target || !shouldLoad) return
+
+    target.postMessage(
+      {
+        type: 'tanstack-charts:embed',
+        version: 1,
+        command: 'set-theme',
+        caseId: chartEmbed.caseId,
+        theme: resolvedEmbedTheme,
+      },
+      chartEmbed.origin,
+    )
+  }, [chartEmbed, resolvedEmbedTheme, shouldLoad])
+
+  React.useEffect(() => {
+    const target = frameRef.current?.contentWindow
+    if (!chartEmbed || !target || !shouldLoad) return
+
+    const handleMessage = (event: MessageEvent<unknown>) => {
+      if (
+        event.origin !== chartEmbed.origin ||
+        event.source !== target ||
+        !isReadyChartEmbedMessage(event.data, chartEmbed.caseId)
+      ) {
+        return
+      }
+      postChartTheme()
+    }
+
+    window.addEventListener('message', handleMessage)
+    postChartTheme()
+    return () => window.removeEventListener('message', handleMessage)
+  }, [chartEmbed, postChartTheme, shouldLoad])
+
+  if (!chartEmbed) return null
+
+  return (
+    <iframe
+      title={iframeTitle}
+      {...iframeProps}
+      ref={frameRef}
+      src={shouldLoad ? src : undefined}
+      loading={loading}
+      referrerPolicy="strict-origin-when-cross-origin"
+      className={`block w-full ${className ?? ''}`.trim()}
+      data-chart-catalog-embed={chartEmbed.caseId}
+      onLoad={(event) => {
+        onLoad?.(event)
+        postChartTheme()
+      }}
+    />
+  )
+}
+
+function isReadyChartEmbedMessage(value: unknown, caseId: string) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'type' in value &&
+    value.type === 'tanstack-charts:embed' &&
+    'version' in value &&
+    value.version === 1 &&
+    'status' in value &&
+    value.status === 'ready' &&
+    'caseId' in value &&
+    value.caseId === caseId
+  )
+}
diff --git a/src/components/charts/ChartsCatalogPages.tsx b/src/components/charts/ChartsCatalogPages.tsx
new file mode 100644
index 000000000..781476cee
--- /dev/null
+++ b/src/components/charts/ChartsCatalogPages.tsx
@@ -0,0 +1,384 @@
+import { Link } from '@tanstack/react-router'
+import * as React from 'react'
+import type { ChartsCatalogCase } from '~/utils/charts-catalog'
+import {
+  ChartsCatalogChart,
+  type ChartsCatalogModuleReference,
+} from './ChartsCatalogChart'
+
+type CatalogCaseMetadata = Pick<
+  ChartsCatalogCase,
+  | 'ai'
+  | 'family'
+  | 'features'
+  | 'geometry'
+  | 'id'
+  | 'intent'
+  | 'order'
+  | 'referenceRenderer'
+  | 'routes'
+  | 'schemaVersion'
+  | 'source'
+  | 'support'
+  | 'title'
+>
+
+type CatalogCaseModules = {
+  tanstack: ChartsCatalogModuleReference
+  comparison?: ChartsCatalogModuleReference & {
+    renderer: 'observable-plot' | 'recharts' | 'echarts'
+    visibility: 'debug'
+  }
+}
+
+export function ChartsCatalogIndex({
+  cases,
+}: {
+  cases: Array<CatalogCaseMetadata>
+}) {
+  const [query, setQuery] = React.useState('')
+  const [family, setFamily] = React.useState('all')
+  const families = React.useMemo(
+    () => [...new Set(cases.map((catalogCase) => catalogCase.family))].sort(),
+    [cases],
+  )
+  const filtered = cases.filter((catalogCase) => {
+    const matchesFamily = family === 'all' || catalogCase.family === family
+    const search = query.trim().toLowerCase()
+    return (
+      matchesFamily &&
+      (!search ||
+        catalogCase.title.toLowerCase().includes(search) ||
+        catalogCase.features.some((feature) =>
+          feature.toLowerCase().includes(search),
+        ))
+    )
+  })
+
+  return (
+    <CatalogSurface>
+      <CatalogToolbar
+        count={filtered.length}
+        family={family}
+        families={families}
+        query={query}
+        setFamily={setFamily}
+        setQuery={setQuery}
+      />
+      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+        {filtered.map((catalogCase) => (
+          <Link
+            key={catalogCase.id}
+            to="/charts/catalog/charts/$caseId"
+            params={{ caseId: catalogCase.id }}
+            search={true}
+            className="group rounded-xl border border-gray-200 bg-white p-4 transition-colors hover:border-blue-400 dark:border-gray-800 dark:bg-gray-950 dark:hover:border-blue-600"
+          >
+            <div className="flex items-start justify-between gap-4">
+              <h2 className="font-semibold leading-snug text-gray-950 group-hover:text-blue-600 dark:text-white dark:group-hover:text-blue-400">
+                {catalogCase.title}
+              </h2>
+              <span className="shrink-0 font-mono text-xs text-gray-400">
+                {String(catalogCase.order).padStart(2, '0')}
+              </span>
+            </div>
+            <p className="mt-3 text-xs text-gray-500 dark:text-gray-400">
+              {catalogCase.family}
+            </p>
+          </Link>
+        ))}
+      </div>
+    </CatalogSurface>
+  )
+}
+
+export function ChartsCatalogAll({
+  artifactRevision,
+  cases,
+}: {
+  artifactRevision: string
+  cases: Array<CatalogCaseMetadata & { modules: CatalogCaseModules }>
+}) {
+  const [query, setQuery] = React.useState('')
+  const [family, setFamily] = React.useState('all')
+  const families = React.useMemo(
+    () => [...new Set(cases.map((catalogCase) => catalogCase.family))].sort(),
+    [cases],
+  )
+  const filtered = cases.filter((catalogCase) => {
+    const search = query.trim().toLowerCase()
+    return (
+      (family === 'all' || catalogCase.family === family) &&
+      (!search || catalogCase.title.toLowerCase().includes(search))
+    )
+  })
+
+  return (
+    <CatalogSurface wide>
+      <CatalogToolbar
+        count={filtered.length}
+        family={family}
+        families={families}
+        query={query}
+        setFamily={setFamily}
+        setQuery={setQuery}
+      />
+      <div className="space-y-4">
+        {filtered.map((catalogCase) => (
+          <article
+            key={catalogCase.id}
+            className="rounded-xl border border-gray-200 bg-white p-4 dark:border-gray-800 dark:bg-gray-950"
+          >
+            <div className="mb-4 flex items-center justify-between gap-4">
+              <Link
+                to="/charts/catalog/charts/$caseId"
+                params={{ caseId: catalogCase.id }}
+                search={true}
+                className="font-semibold text-gray-950 hover:text-blue-600 dark:text-white dark:hover:text-blue-400"
+              >
+                {catalogCase.title}
+              </Link>
+              <span className="text-xs text-gray-500">
+                {catalogCase.family}
+              </span>
+            </div>
+            <div
+              className={
+                catalogCase.modules.comparison
+                  ? 'grid gap-6 xl:grid-cols-2'
+                  : ''
+              }
+            >
+              <ChartPanel label="TanStack">
+                <ChartsCatalogChart
+                  artifactRevision={artifactRevision}
+                  caseId={catalogCase.id}
+                  defer
+                  module={catalogCase.modules.tanstack}
+                />
+              </ChartPanel>
+              {catalogCase.modules.comparison ? (
+                <ChartPanel
+                  label={rendererLabel(catalogCase.modules.comparison.renderer)}
+                >
+                  <ChartsCatalogChart
+                    artifactRevision={artifactRevision}
+                    caseId={`${catalogCase.id}-comparison`}
+                    defer
+                    module={catalogCase.modules.comparison}
+                  />
+                </ChartPanel>
+              ) : null}
+            </div>
+          </article>
+        ))}
+      </div>
+    </CatalogSurface>
+  )
+}
+
+export function ChartsCatalogDetail({
+  artifactRevision,
+  catalogCase,
+}: {
+  artifactRevision: string
+  catalogCase: CatalogCaseMetadata & {
+    modules: CatalogCaseModules
+    code: {
+      tanstack: { path: string; source: string }
+      comparison?: { path: string; source?: string }
+    }
+  }
+}) {
+  const [revision, setRevision] = React.useState(0)
+  const [width, setWidth] = React.useState<'wide' | 'compact'>('wide')
+  const comparison = catalogCase.modules.comparison
+
+  return (
+    <CatalogSurface wide>
+      <div className="mb-6 flex flex-wrap items-start justify-between gap-5">
+        <div>
+          <Link
+            to="/charts/catalog"
+            search={true}
+            className="text-sm text-gray-500 hover:text-blue-600 dark:hover:text-blue-400"
+          >
+            Catalog
+          </Link>
+          <h1 className="mt-2 text-2xl font-bold tracking-tight text-gray-950 dark:text-white sm:text-3xl">
+            {catalogCase.title}
+          </h1>
+          <div className="mt-3 flex items-center gap-3 text-xs text-gray-500">
+            <span>{catalogCase.family}</span>
+            <a
+              href={catalogCase.source.url}
+              rel="noreferrer"
+              target="_blank"
+              className="hover:text-blue-600 dark:hover:text-blue-400"
+            >
+              Reference
+            </a>
+          </div>
+        </div>
+        <div className="flex rounded-lg border border-gray-200 p-1 text-xs dark:border-gray-800">
+          <button
+            type="button"
+            className={`rounded px-3 py-2 ${width === 'compact' ? 'bg-gray-100 dark:bg-gray-800' : ''}`}
+            onClick={() => setWidth('compact')}
+          >
+            640
+          </button>
+          <button
+            type="button"
+            className={`rounded px-3 py-2 ${width === 'wide' ? 'bg-gray-100 dark:bg-gray-800' : ''}`}
+            onClick={() => setWidth('wide')}
+          >
+            960
+          </button>
+          <button
+            type="button"
+            className="rounded px-3 py-2 hover:bg-gray-100 dark:hover:bg-gray-800"
+            onClick={() => setRevision((value) => (value === 0 ? 1 : 0))}
+          >
+            Revision {revision}
+          </button>
+        </div>
+      </div>
+
+      <div
+        className={`mx-auto grid gap-6 ${comparison ? 'xl:grid-cols-2' : ''} ${
+          width === 'compact' ? 'max-w-2xl' : ''
+        }`}
+      >
+        <ChartPanel label="TanStack">
+          <ChartsCatalogChart
+            artifactRevision={artifactRevision}
+            caseId={catalogCase.id}
+            module={catalogCase.modules.tanstack}
+            revision={revision}
+          />
+        </ChartPanel>
+        {comparison ? (
+          <ChartPanel label={rendererLabel(comparison.renderer)}>
+            <ChartsCatalogChart
+              artifactRevision={artifactRevision}
+              caseId={`${catalogCase.id}-comparison`}
+              module={comparison}
+              revision={revision}
+            />
+          </ChartPanel>
+        ) : null}
+      </div>
+
+      <div className={`mt-6 grid gap-3 ${comparison ? 'xl:grid-cols-2' : ''}`}>
+        <SourceBlock
+          path={catalogCase.code.tanstack.path}
+          source={catalogCase.code.tanstack.source}
+        />
+        {catalogCase.code.comparison?.source ? (
+          <SourceBlock
+            path={catalogCase.code.comparison.path}
+            source={catalogCase.code.comparison.source}
+          />
+        ) : null}
+      </div>
+    </CatalogSurface>
+  )
+}
+
+function CatalogSurface({
+  children,
+  wide = false,
+}: {
+  children: React.ReactNode
+  wide?: boolean
+}) {
+  return (
+    <main
+      className={`mx-auto min-h-[calc(100vh-var(--navbar-height))] px-4 py-8 ${
+        wide ? 'max-w-[1680px]' : 'max-w-6xl'
+      }`}
+    >
+      {children}
+    </main>
+  )
+}
+
+function CatalogToolbar({
+  count,
+  family,
+  families,
+  query,
+  setFamily,
+  setQuery,
+}: {
+  count: number
+  family: string
+  families: Array<string>
+  query: string
+  setFamily: (family: string) => void
+  setQuery: (query: string) => void
+}) {
+  return (
+    <div className="mb-6 flex flex-wrap items-center gap-3">
+      <input
+        aria-label="Search charts"
+        type="search"
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+        placeholder="Search"
+        className="min-w-56 flex-1 rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm outline-none focus:border-blue-500 dark:border-gray-800 dark:bg-gray-950"
+      />
+      <select
+        aria-label="Chart family"
+        value={family}
+        onChange={(event) => setFamily(event.target.value)}
+        className="rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm dark:border-gray-800 dark:bg-gray-950"
+      >
+        <option value="all">All families</option>
+        {families.map((value) => (
+          <option key={value} value={value}>
+            {value}
+          </option>
+        ))}
+      </select>
+      <span className="w-16 text-right font-mono text-xs text-gray-500">
+        {count}
+      </span>
+    </div>
+  )
+}
+
+function ChartPanel({
+  children,
+  label,
+}: {
+  children: React.ReactNode
+  label: string
+}) {
+  return (
+    <div className="min-w-0">
+      <p className="mb-2 text-xs font-medium text-gray-500">{label}</p>
+      {children}
+    </div>
+  )
+}
+
+function SourceBlock({ path, source }: { path: string; source: string }) {
+  return (
+    <details className="min-w-0 rounded-lg border border-gray-200 dark:border-gray-800">
+      <summary className="cursor-pointer px-4 py-3 font-mono text-xs text-gray-600 dark:text-gray-400">
+        {path}
+      </summary>
+      <pre className="max-h-[32rem] overflow-auto border-t border-gray-200 p-4 text-xs dark:border-gray-800">
+        <code>{source}</code>
+      </pre>
+    </details>
+  )
+}
+
+function rendererLabel(renderer: 'observable-plot' | 'recharts' | 'echarts') {
+  if (renderer === 'observable-plot') return 'Observable Plot'
+  if (renderer === 'recharts') return 'Recharts'
+  return 'Apache ECharts'
+}
diff --git a/src/routeTree.gen.ts b/src/routeTree.gen.ts
index 275234d12..4ddabf1d0 100644
--- a/src/routeTree.gen.ts
+++ b/src/routeTree.gen.ts
@@ -62,6 +62,7 @@ import { Route as OauthTokenRouteImport } from './routes/oauth/token'
 import { Route as OauthRegisterRouteImport } from './routes/oauth/register'
 import { Route as OauthAuthorizeRouteImport } from './routes/oauth/authorize'
 import { Route as LibrariesFrameworkRouteImport } from './routes/libraries_.$framework'
+import { Route as ChartsCatalogRouteImport } from './routes/charts.catalog'
 import { Route as BuilderDocsRouteImport } from './routes/builder.docs'
 import { Route as BlogSplatRouteImport } from './routes/blog.$'
 import { Route as AuthSignoutRouteImport } from './routes/auth/signout'
@@ -83,6 +84,7 @@ import { Route as DotwellKnownOauthAuthorizationServerRouteImport } from './rout
 import { Route as LibraryLibraryIdRouteRouteImport } from './routes/_library/$libraryId/route'
 import { Route as StatsNpmIndexRouteImport } from './routes/stats/npm/index'
 import { Route as IntentRegistryIndexRouteImport } from './routes/intent/registry/index'
+import { Route as ChartsCatalogIndexRouteImport } from './routes/charts.catalog.index'
 import { Route as ApiMcpIndexRouteImport } from './routes/api/mcp/index'
 import { Route as AdminShowcasesIndexRouteImport } from './routes/admin/showcases.index'
 import { Route as AdminRolesIndexRouteImport } from './routes/admin/roles.index'
@@ -97,6 +99,8 @@ import { Route as ShopPoliciesHandleRouteImport } from './routes/shop.policies.$
 import { Route as ShopPagesHandleRouteImport } from './routes/shop.pages.$handle'
 import { Route as ShopCollectionsHandleRouteImport } from './routes/shop.collections.$handle'
 import { Route as IntentRegistryPackageNameRouteImport } from './routes/intent/registry/$packageName'
+import { Route as ChartsCatalogCatalogDotjsonRouteImport } from './routes/charts.catalog_.catalog[.]json'
+import { Route as ChartsCatalogAllRouteImport } from './routes/charts.catalog.all'
 import { Route as AuthProviderStartRouteImport } from './routes/auth/$provider/start'
 import { Route as ApiOgChar123Char125DotpngRouteImport } from './routes/api/og/{$}[.]png'
 import { Route as ApiMcpSplatRouteImport } from './routes/api/mcp/$'
@@ -144,6 +148,8 @@ import { Route as LibraryAiVersionIndexRouteImport } from './routes/_library/ai.
 import { Route as LibraryLibraryIdVersionIndexRouteImport } from './routes/_library/$libraryId/$version.index'
 import { Route as IntentRegistryPackageNameChar123Char125DotmdRouteImport } from './routes/intent/registry/$packageName.{$}[.]md'
 import { Route as IntentRegistryPackageNameSkillNameRouteImport } from './routes/intent/registry/$packageName.$skillName'
+import { Route as ChartsCatalogEmbedCaseIdRouteImport } from './routes/charts.catalog_.embed.$caseId'
+import { Route as ChartsCatalogChartsCaseIdRouteImport } from './routes/charts.catalog.charts.$caseId'
 import { Route as ApiBuilderDeployGithubRouteImport } from './routes/api/builder/deploy/github'
 import { Route as ApiBuilderDeployCheckNameRouteImport } from './routes/api/builder/deploy/check-name'
 import { Route as ApiAuthCliCreateTicketRouteImport } from './routes/api/auth/cli/create-ticket'
@@ -151,6 +157,7 @@ import { Route as ApiAuthCallbackProviderRouteImport } from './routes/api/auth/c
 import { Route as LibraryLibraryIdVersionLlmsDottxtRouteImport } from './routes/_library/$libraryId/$version.llms[.]txt'
 import { Route as LibraryLibraryIdVersionDocsRouteImport } from './routes/_library/$libraryId/$version.docs'
 import { Route as LibraryLibraryIdVersionDocsIndexRouteImport } from './routes/_library/$libraryId/$version.docs.index'
+import { Route as ChartsCatalogAssetsArtifactRevisionSplatRouteImport } from './routes/charts.catalog_.assets.$artifactRevision.$'
 import { Route as ApiAuthCliStatusTicketIdRouteImport } from './routes/api/auth/cli/status.$ticketId'
 import { Route as LibraryLibraryIdVersionDocsChar123Char125DotmdRouteImport } from './routes/_library/$libraryId/$version.docs.{$}[.]md'
 import { Route as LibraryLibraryIdVersionDocsNpmStatsRouteImport } from './routes/_library/$libraryId/$version.docs.npm-stats'
@@ -429,6 +436,11 @@ const LibrariesFrameworkRoute = LibrariesFrameworkRouteImport.update({
   path: '/libraries/$framework',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ChartsCatalogRoute = ChartsCatalogRouteImport.update({
+  id: '/charts/catalog',
+  path: '/charts/catalog',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const BuilderDocsRoute = BuilderDocsRouteImport.update({
   id: '/docs',
   path: '/docs',
@@ -535,6 +547,11 @@ const IntentRegistryIndexRoute = IntentRegistryIndexRouteImport.update({
   path: '/intent/registry/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ChartsCatalogIndexRoute = ChartsCatalogIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => ChartsCatalogRoute,
+} as any)
 const ApiMcpIndexRoute = ApiMcpIndexRouteImport.update({
   id: '/api/mcp/',
   path: '/api/mcp/',
@@ -606,6 +623,17 @@ const IntentRegistryPackageNameRoute =
     path: '/intent/registry/$packageName',
     getParentRoute: () => rootRouteImport,
   } as any)
+const ChartsCatalogCatalogDotjsonRoute =
+  ChartsCatalogCatalogDotjsonRouteImport.update({
+    id: '/charts/catalog_/catalog.json',
+    path: '/charts/catalog/catalog.json',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ChartsCatalogAllRoute = ChartsCatalogAllRouteImport.update({
+  id: '/all',
+  path: '/all',
+  getParentRoute: () => ChartsCatalogRoute,
+} as any)
 const AuthProviderStartRoute = AuthProviderStartRouteImport.update({
   id: '/auth/$provider/start',
   path: '/auth/$provider/start',
@@ -866,6 +894,18 @@ const IntentRegistryPackageNameSkillNameRoute =
     path: '/$skillName',
     getParentRoute: () => IntentRegistryPackageNameRoute,
   } as any)
+const ChartsCatalogEmbedCaseIdRoute =
+  ChartsCatalogEmbedCaseIdRouteImport.update({
+    id: '/charts/catalog_/embed/$caseId',
+    path: '/charts/catalog/embed/$caseId',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ChartsCatalogChartsCaseIdRoute =
+  ChartsCatalogChartsCaseIdRouteImport.update({
+    id: '/charts/$caseId',
+    path: '/charts/$caseId',
+    getParentRoute: () => ChartsCatalogRoute,
+  } as any)
 const ApiBuilderDeployGithubRoute = ApiBuilderDeployGithubRouteImport.update({
   id: '/api/builder/deploy/github',
   path: '/api/builder/deploy/github',
@@ -905,6 +945,12 @@ const LibraryLibraryIdVersionDocsIndexRoute =
     path: '/',
     getParentRoute: () => LibraryLibraryIdVersionDocsRoute,
   } as any)
+const ChartsCatalogAssetsArtifactRevisionSplatRoute =
+  ChartsCatalogAssetsArtifactRevisionSplatRouteImport.update({
+    id: '/charts/catalog_/assets/$artifactRevision/$',
+    path: '/charts/catalog/assets/$artifactRevision/$',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const ApiAuthCliStatusTicketIdRoute =
   ApiAuthCliStatusTicketIdRouteImport.update({
     id: '/api/auth/cli/status/$ticketId',
@@ -1038,6 +1084,7 @@ export interface FileRoutesByFullPath {
   '/auth/signout': typeof AuthSignoutRoute
   '/blog/$': typeof BlogSplatRoute
   '/builder/docs': typeof BuilderDocsRoute
+  '/charts/catalog': typeof ChartsCatalogRouteWithChildren
   '/libraries/$framework': typeof LibrariesFrameworkRoute
   '/oauth/authorize': typeof OauthAuthorizeRoute
   '/oauth/register': typeof OauthRegisterRoute
@@ -1082,6 +1129,8 @@ export interface FileRoutesByFullPath {
   '/api/mcp/$': typeof ApiMcpSplatRoute
   '/api/og/{$}.png': typeof ApiOgChar123Char125DotpngRoute
   '/auth/$provider/start': typeof AuthProviderStartRoute
+  '/charts/catalog/all': typeof ChartsCatalogAllRoute
+  '/charts/catalog/catalog.json': typeof ChartsCatalogCatalogDotjsonRoute
   '/intent/registry/$packageName': typeof IntentRegistryPackageNameRouteWithChildren
   '/shop/collections/$handle': typeof ShopCollectionsHandleRoute
   '/shop/pages/$handle': typeof ShopPagesHandleRoute
@@ -1096,6 +1145,7 @@ export interface FileRoutesByFullPath {
   '/admin/roles/': typeof AdminRolesIndexRoute
   '/admin/showcases/': typeof AdminShowcasesIndexRoute
   '/api/mcp/': typeof ApiMcpIndexRoute
+  '/charts/catalog/': typeof ChartsCatalogIndexRoute
   '/intent/registry/': typeof IntentRegistryIndexRoute
   '/stats/npm/': typeof StatsNpmIndexRoute
   '/$libraryId/$version/docs': typeof LibraryLibraryIdVersionDocsRouteWithChildren
@@ -1104,6 +1154,8 @@ export interface FileRoutesByFullPath {
   '/api/auth/cli/create-ticket': typeof ApiAuthCliCreateTicketRoute
   '/api/builder/deploy/check-name': typeof ApiBuilderDeployCheckNameRoute
   '/api/builder/deploy/github': typeof ApiBuilderDeployGithubRoute
+  '/charts/catalog/charts/$caseId': typeof ChartsCatalogChartsCaseIdRoute
+  '/charts/catalog/embed/$caseId': typeof ChartsCatalogEmbedCaseIdRoute
   '/intent/registry/$packageName/$skillName': typeof IntentRegistryPackageNameSkillNameRoute
   '/intent/registry/$packageName/{$}.md': typeof IntentRegistryPackageNameChar123Char125DotmdRoute
   '/$libraryId/$version/': typeof LibraryLibraryIdVersionIndexRoute
@@ -1135,6 +1187,7 @@ export interface FileRoutesByFullPath {
   '/$libraryId/$version/docs/npm-stats': typeof LibraryLibraryIdVersionDocsNpmStatsRoute
   '/$libraryId/$version/docs/{$}.md': typeof LibraryLibraryIdVersionDocsChar123Char125DotmdRoute
   '/api/auth/cli/status/$ticketId': typeof ApiAuthCliStatusTicketIdRoute
+  '/charts/catalog/assets/$artifactRevision/$': typeof ChartsCatalogAssetsArtifactRevisionSplatRoute
   '/$libraryId/$version/docs/': typeof LibraryLibraryIdVersionDocsIndexRoute
   '/$libraryId/$version/docs/framework/': typeof LibraryLibraryIdVersionDocsFrameworkIndexRoute
   '/$libraryId/$version/docs/framework/$framework/$': typeof LibraryLibraryIdVersionDocsFrameworkFrameworkSplatRoute
@@ -1230,6 +1283,8 @@ export interface FileRoutesByTo {
   '/api/mcp/$': typeof ApiMcpSplatRoute
   '/api/og/{$}.png': typeof ApiOgChar123Char125DotpngRoute
   '/auth/$provider/start': typeof AuthProviderStartRoute
+  '/charts/catalog/all': typeof ChartsCatalogAllRoute
+  '/charts/catalog/catalog.json': typeof ChartsCatalogCatalogDotjsonRoute
   '/shop/collections/$handle': typeof ShopCollectionsHandleRoute
   '/shop/pages/$handle': typeof ShopPagesHandleRoute
   '/shop/policies/$handle': typeof ShopPoliciesHandleRoute
@@ -1243,6 +1298,7 @@ export interface FileRoutesByTo {
   '/admin/roles': typeof AdminRolesIndexRoute
   '/admin/showcases': typeof AdminShowcasesIndexRoute
   '/api/mcp': typeof ApiMcpIndexRoute
+  '/charts/catalog': typeof ChartsCatalogIndexRoute
   '/intent/registry': typeof IntentRegistryIndexRoute
   '/stats/npm': typeof StatsNpmIndexRoute
   '/$libraryId/$version/llms.txt': typeof LibraryLibraryIdVersionLlmsDottxtRoute
@@ -1250,6 +1306,8 @@ export interface FileRoutesByTo {
   '/api/auth/cli/create-ticket': typeof ApiAuthCliCreateTicketRoute
   '/api/builder/deploy/check-name': typeof ApiBuilderDeployCheckNameRoute
   '/api/builder/deploy/github': typeof ApiBuilderDeployGithubRoute
+  '/charts/catalog/charts/$caseId': typeof ChartsCatalogChartsCaseIdRoute
+  '/charts/catalog/embed/$caseId': typeof ChartsCatalogEmbedCaseIdRoute
   '/intent/registry/$packageName/$skillName': typeof IntentRegistryPackageNameSkillNameRoute
   '/intent/registry/$packageName/{$}.md': typeof IntentRegistryPackageNameChar123Char125DotmdRoute
   '/$libraryId/$version': typeof LibraryLibraryIdVersionIndexRoute
@@ -1281,6 +1339,7 @@ export interface FileRoutesByTo {
   '/$libraryId/$version/docs/npm-stats': typeof LibraryLibraryIdVersionDocsNpmStatsRoute
   '/$libraryId/$version/docs/{$}.md': typeof LibraryLibraryIdVersionDocsChar123Char125DotmdRoute
   '/api/auth/cli/status/$ticketId': typeof ApiAuthCliStatusTicketIdRoute
+  '/charts/catalog/assets/$artifactRevision/$': typeof ChartsCatalogAssetsArtifactRevisionSplatRoute
   '/$libraryId/$version/docs': typeof LibraryLibraryIdVersionDocsIndexRoute
   '/$libraryId/$version/docs/framework': typeof LibraryLibraryIdVersionDocsFrameworkIndexRoute
   '/$libraryId/$version/docs/framework/$framework/$': typeof LibraryLibraryIdVersionDocsFrameworkFrameworkSplatRoute
@@ -1342,6 +1401,7 @@ export interface FileRoutesById {
   '/auth/signout': typeof AuthSignoutRoute
   '/blog/$': typeof BlogSplatRoute
   '/builder/docs': typeof BuilderDocsRoute
+  '/charts/catalog': typeof ChartsCatalogRouteWithChildren
   '/libraries_/$framework': typeof LibrariesFrameworkRoute
   '/oauth/authorize': typeof OauthAuthorizeRoute
   '/oauth/register': typeof OauthRegisterRoute
@@ -1386,6 +1446,8 @@ export interface FileRoutesById {
   '/api/mcp/$': typeof ApiMcpSplatRoute
   '/api/og/{$}.png': typeof ApiOgChar123Char125DotpngRoute
   '/auth/$provider/start': typeof AuthProviderStartRoute
+  '/charts/catalog/all': typeof ChartsCatalogAllRoute
+  '/charts/catalog_/catalog.json': typeof ChartsCatalogCatalogDotjsonRoute
   '/intent/registry/$packageName': typeof IntentRegistryPackageNameRouteWithChildren
   '/shop/collections/$handle': typeof ShopCollectionsHandleRoute
   '/shop/pages/$handle': typeof ShopPagesHandleRoute
@@ -1400,6 +1462,7 @@ export interface FileRoutesById {
   '/admin/roles/': typeof AdminRolesIndexRoute
   '/admin/showcases/': typeof AdminShowcasesIndexRoute
   '/api/mcp/': typeof ApiMcpIndexRoute
+  '/charts/catalog/': typeof ChartsCatalogIndexRoute
   '/intent/registry/': typeof IntentRegistryIndexRoute
   '/stats/npm/': typeof StatsNpmIndexRoute
   '/_library/$libraryId/$version/docs': typeof LibraryLibraryIdVersionDocsRouteWithChildren
@@ -1408,6 +1471,8 @@ export interface FileRoutesById {
   '/api/auth/cli/create-ticket': typeof ApiAuthCliCreateTicketRoute
   '/api/builder/deploy/check-name': typeof ApiBuilderDeployCheckNameRoute
   '/api/builder/deploy/github': typeof ApiBuilderDeployGithubRoute
+  '/charts/catalog/charts/$caseId': typeof ChartsCatalogChartsCaseIdRoute
+  '/charts/catalog_/embed/$caseId': typeof ChartsCatalogEmbedCaseIdRoute
   '/intent/registry/$packageName/$skillName': typeof IntentRegistryPackageNameSkillNameRoute
   '/intent/registry/$packageName/{$}.md': typeof IntentRegistryPackageNameChar123Char125DotmdRoute
   '/_library/$libraryId/$version/': typeof LibraryLibraryIdVersionIndexRoute
@@ -1439,6 +1504,7 @@ export interface FileRoutesById {
   '/_library/$libraryId/$version/docs/npm-stats': typeof LibraryLibraryIdVersionDocsNpmStatsRoute
   '/_library/$libraryId/$version/docs/{$}.md': typeof LibraryLibraryIdVersionDocsChar123Char125DotmdRoute
   '/api/auth/cli/status/$ticketId': typeof ApiAuthCliStatusTicketIdRoute
+  '/charts/catalog_/assets/$artifactRevision/$': typeof ChartsCatalogAssetsArtifactRevisionSplatRoute
   '/_library/$libraryId/$version/docs/': typeof LibraryLibraryIdVersionDocsIndexRoute
   '/_library/$libraryId/$version/docs/framework/': typeof LibraryLibraryIdVersionDocsFrameworkIndexRoute
   '/_library/$libraryId/$version/docs/framework/$framework/$': typeof LibraryLibraryIdVersionDocsFrameworkFrameworkSplatRoute
@@ -1500,6 +1566,7 @@ export interface FileRouteTypes {
     | '/auth/signout'
     | '/blog/$'
     | '/builder/docs'
+    | '/charts/catalog'
     | '/libraries/$framework'
     | '/oauth/authorize'
     | '/oauth/register'
@@ -1544,6 +1611,8 @@ export interface FileRouteTypes {
     | '/api/mcp/$'
     | '/api/og/{$}.png'
     | '/auth/$provider/start'
+    | '/charts/catalog/all'
+    | '/charts/catalog/catalog.json'
     | '/intent/registry/$packageName'
     | '/shop/collections/$handle'
     | '/shop/pages/$handle'
@@ -1558,6 +1627,7 @@ export interface FileRouteTypes {
     | '/admin/roles/'
     | '/admin/showcases/'
     | '/api/mcp/'
+    | '/charts/catalog/'
     | '/intent/registry/'
     | '/stats/npm/'
     | '/$libraryId/$version/docs'
@@ -1566,6 +1636,8 @@ export interface FileRouteTypes {
     | '/api/auth/cli/create-ticket'
     | '/api/builder/deploy/check-name'
     | '/api/builder/deploy/github'
+    | '/charts/catalog/charts/$caseId'
+    | '/charts/catalog/embed/$caseId'
     | '/intent/registry/$packageName/$skillName'
     | '/intent/registry/$packageName/{$}.md'
     | '/$libraryId/$version/'
@@ -1597,6 +1669,7 @@ export interface FileRouteTypes {
     | '/$libraryId/$version/docs/npm-stats'
     | '/$libraryId/$version/docs/{$}.md'
     | '/api/auth/cli/status/$ticketId'
+    | '/charts/catalog/assets/$artifactRevision/$'
     | '/$libraryId/$version/docs/'
     | '/$libraryId/$version/docs/framework/'
     | '/$libraryId/$version/docs/framework/$framework/$'
@@ -1692,6 +1765,8 @@ export interface FileRouteTypes {
     | '/api/mcp/$'
     | '/api/og/{$}.png'
     | '/auth/$provider/start'
+    | '/charts/catalog/all'
+    | '/charts/catalog/catalog.json'
     | '/shop/collections/$handle'
     | '/shop/pages/$handle'
     | '/shop/policies/$handle'
@@ -1705,6 +1780,7 @@ export interface FileRouteTypes {
     | '/admin/roles'
     | '/admin/showcases'
     | '/api/mcp'
+    | '/charts/catalog'
     | '/intent/registry'
     | '/stats/npm'
     | '/$libraryId/$version/llms.txt'
@@ -1712,6 +1788,8 @@ export interface FileRouteTypes {
     | '/api/auth/cli/create-ticket'
     | '/api/builder/deploy/check-name'
     | '/api/builder/deploy/github'
+    | '/charts/catalog/charts/$caseId'
+    | '/charts/catalog/embed/$caseId'
     | '/intent/registry/$packageName/$skillName'
     | '/intent/registry/$packageName/{$}.md'
     | '/$libraryId/$version'
@@ -1743,6 +1821,7 @@ export interface FileRouteTypes {
     | '/$libraryId/$version/docs/npm-stats'
     | '/$libraryId/$version/docs/{$}.md'
     | '/api/auth/cli/status/$ticketId'
+    | '/charts/catalog/assets/$artifactRevision/$'
     | '/$libraryId/$version/docs'
     | '/$libraryId/$version/docs/framework'
     | '/$libraryId/$version/docs/framework/$framework/$'
@@ -1803,6 +1882,7 @@ export interface FileRouteTypes {
     | '/auth/signout'
     | '/blog/$'
     | '/builder/docs'
+    | '/charts/catalog'
     | '/libraries_/$framework'
     | '/oauth/authorize'
     | '/oauth/register'
@@ -1847,6 +1927,8 @@ export interface FileRouteTypes {
     | '/api/mcp/$'
     | '/api/og/{$}.png'
     | '/auth/$provider/start'
+    | '/charts/catalog/all'
+    | '/charts/catalog_/catalog.json'
     | '/intent/registry/$packageName'
     | '/shop/collections/$handle'
     | '/shop/pages/$handle'
@@ -1861,6 +1943,7 @@ export interface FileRouteTypes {
     | '/admin/roles/'
     | '/admin/showcases/'
     | '/api/mcp/'
+    | '/charts/catalog/'
     | '/intent/registry/'
     | '/stats/npm/'
     | '/_library/$libraryId/$version/docs'
@@ -1869,6 +1952,8 @@ export interface FileRouteTypes {
     | '/api/auth/cli/create-ticket'
     | '/api/builder/deploy/check-name'
     | '/api/builder/deploy/github'
+    | '/charts/catalog/charts/$caseId'
+    | '/charts/catalog_/embed/$caseId'
     | '/intent/registry/$packageName/$skillName'
     | '/intent/registry/$packageName/{$}.md'
     | '/_library/$libraryId/$version/'
@@ -1900,6 +1985,7 @@ export interface FileRouteTypes {
     | '/_library/$libraryId/$version/docs/npm-stats'
     | '/_library/$libraryId/$version/docs/{$}.md'
     | '/api/auth/cli/status/$ticketId'
+    | '/charts/catalog_/assets/$artifactRevision/$'
     | '/_library/$libraryId/$version/docs/'
     | '/_library/$libraryId/$version/docs/framework/'
     | '/_library/$libraryId/$version/docs/framework/$framework/$'
@@ -1947,6 +2033,7 @@ export interface RootRouteChildren {
   AuthCliRoute: typeof AuthCliRoute
   AuthPopupSuccessRoute: typeof AuthPopupSuccessRoute
   AuthSignoutRoute: typeof AuthSignoutRoute
+  ChartsCatalogRoute: typeof ChartsCatalogRouteWithChildren
   LibrariesFrameworkRoute: typeof LibrariesFrameworkRoute
   OauthAuthorizeRoute: typeof OauthAuthorizeRoute
   OauthRegisterRoute: typeof OauthRegisterRoute
@@ -1975,6 +2062,7 @@ export interface RootRouteChildren {
   ApiMcpSplatRoute: typeof ApiMcpSplatRoute
   ApiOgChar123Char125DotpngRoute: typeof ApiOgChar123Char125DotpngRoute
   AuthProviderStartRoute: typeof AuthProviderStartRoute
+  ChartsCatalogCatalogDotjsonRoute: typeof ChartsCatalogCatalogDotjsonRoute
   IntentRegistryPackageNameRoute: typeof IntentRegistryPackageNameRouteWithChildren
   ShowcaseEditIdRoute: typeof ShowcaseEditIdRoute
   StatsNpmPackagesRoute: typeof StatsNpmPackagesRoute
@@ -1986,7 +2074,9 @@ export interface RootRouteChildren {
   ApiAuthCliCreateTicketRoute: typeof ApiAuthCliCreateTicketRoute
   ApiBuilderDeployCheckNameRoute: typeof ApiBuilderDeployCheckNameRoute
   ApiBuilderDeployGithubRoute: typeof ApiBuilderDeployGithubRoute
+  ChartsCatalogEmbedCaseIdRoute: typeof ChartsCatalogEmbedCaseIdRoute
   ApiAuthCliStatusTicketIdRoute: typeof ApiAuthCliStatusTicketIdRoute
+  ChartsCatalogAssetsArtifactRevisionSplatRoute: typeof ChartsCatalogAssetsArtifactRevisionSplatRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -2362,6 +2452,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LibrariesFrameworkRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/charts/catalog': {
+      id: '/charts/catalog'
+      path: '/charts/catalog'
+      fullPath: '/charts/catalog'
+      preLoaderRoute: typeof ChartsCatalogRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/builder/docs': {
       id: '/builder/docs'
       path: '/docs'
@@ -2509,6 +2606,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IntentRegistryIndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/charts/catalog/': {
+      id: '/charts/catalog/'
+      path: '/'
+      fullPath: '/charts/catalog/'
+      preLoaderRoute: typeof ChartsCatalogIndexRouteImport
+      parentRoute: typeof ChartsCatalogRoute
+    }
     '/api/mcp/': {
       id: '/api/mcp/'
       path: '/api/mcp'
@@ -2607,6 +2711,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IntentRegistryPackageNameRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/charts/catalog_/catalog.json': {
+      id: '/charts/catalog_/catalog.json'
+      path: '/charts/catalog/catalog.json'
+      fullPath: '/charts/catalog/catalog.json'
+      preLoaderRoute: typeof ChartsCatalogCatalogDotjsonRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/charts/catalog/all': {
+      id: '/charts/catalog/all'
+      path: '/all'
+      fullPath: '/charts/catalog/all'
+      preLoaderRoute: typeof ChartsCatalogAllRouteImport
+      parentRoute: typeof ChartsCatalogRoute
+    }
     '/auth/$provider/start': {
       id: '/auth/$provider/start'
       path: '/auth/$provider/start'
@@ -2936,6 +3054,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IntentRegistryPackageNameSkillNameRouteImport
       parentRoute: typeof IntentRegistryPackageNameRoute
     }
+    '/charts/catalog_/embed/$caseId': {
+      id: '/charts/catalog_/embed/$caseId'
+      path: '/charts/catalog/embed/$caseId'
+      fullPath: '/charts/catalog/embed/$caseId'
+      preLoaderRoute: typeof ChartsCatalogEmbedCaseIdRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/charts/catalog/charts/$caseId': {
+      id: '/charts/catalog/charts/$caseId'
+      path: '/charts/$caseId'
+      fullPath: '/charts/catalog/charts/$caseId'
+      preLoaderRoute: typeof ChartsCatalogChartsCaseIdRouteImport
+      parentRoute: typeof ChartsCatalogRoute
+    }
     '/api/builder/deploy/github': {
       id: '/api/builder/deploy/github'
       path: '/api/builder/deploy/github'
@@ -2985,6 +3117,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LibraryLibraryIdVersionDocsIndexRouteImport
       parentRoute: typeof LibraryLibraryIdVersionDocsRoute
     }
+    '/charts/catalog_/assets/$artifactRevision/$': {
+      id: '/charts/catalog_/assets/$artifactRevision/$'
+      path: '/charts/catalog/assets/$artifactRevision/$'
+      fullPath: '/charts/catalog/assets/$artifactRevision/$'
+      preLoaderRoute: typeof ChartsCatalogAssetsArtifactRevisionSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/auth/cli/status/$ticketId': {
       id: '/api/auth/cli/status/$ticketId'
       path: '/api/auth/cli/status/$ticketId'
@@ -3349,6 +3488,22 @@ const ShopRouteChildren: ShopRouteChildren = {
 
 const ShopRouteWithChildren = ShopRoute._addFileChildren(ShopRouteChildren)
 
+interface ChartsCatalogRouteChildren {
+  ChartsCatalogAllRoute: typeof ChartsCatalogAllRoute
+  ChartsCatalogIndexRoute: typeof ChartsCatalogIndexRoute
+  ChartsCatalogChartsCaseIdRoute: typeof ChartsCatalogChartsCaseIdRoute
+}
+
+const ChartsCatalogRouteChildren: ChartsCatalogRouteChildren = {
+  ChartsCatalogAllRoute: ChartsCatalogAllRoute,
+  ChartsCatalogIndexRoute: ChartsCatalogIndexRoute,
+  ChartsCatalogChartsCaseIdRoute: ChartsCatalogChartsCaseIdRoute,
+}
+
+const ChartsCatalogRouteWithChildren = ChartsCatalogRoute._addFileChildren(
+  ChartsCatalogRouteChildren,
+)
+
 interface IntentRegistryPackageNameRouteChildren {
   IntentRegistryPackageNameSkillNameRoute: typeof IntentRegistryPackageNameSkillNameRoute
   IntentRegistryPackageNameChar123Char125DotmdRoute: typeof IntentRegistryPackageNameChar123Char125DotmdRoute
@@ -3409,6 +3564,7 @@ const rootRouteChildren: RootRouteChildren = {
   AuthCliRoute: AuthCliRoute,
   AuthPopupSuccessRoute: AuthPopupSuccessRoute,
   AuthSignoutRoute: AuthSignoutRoute,
+  ChartsCatalogRoute: ChartsCatalogRouteWithChildren,
   LibrariesFrameworkRoute: LibrariesFrameworkRoute,
   OauthAuthorizeRoute: OauthAuthorizeRoute,
   OauthRegisterRoute: OauthRegisterRoute,
@@ -3437,6 +3593,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiMcpSplatRoute: ApiMcpSplatRoute,
   ApiOgChar123Char125DotpngRoute: ApiOgChar123Char125DotpngRoute,
   AuthProviderStartRoute: AuthProviderStartRoute,
+  ChartsCatalogCatalogDotjsonRoute: ChartsCatalogCatalogDotjsonRoute,
   IntentRegistryPackageNameRoute: IntentRegistryPackageNameRouteWithChildren,
   ShowcaseEditIdRoute: ShowcaseEditIdRoute,
   StatsNpmPackagesRoute: StatsNpmPackagesRoute,
@@ -3448,7 +3605,10 @@ const rootRouteChildren: RootRouteChildren = {
   ApiAuthCliCreateTicketRoute: ApiAuthCliCreateTicketRoute,
   ApiBuilderDeployCheckNameRoute: ApiBuilderDeployCheckNameRoute,
   ApiBuilderDeployGithubRoute: ApiBuilderDeployGithubRoute,
+  ChartsCatalogEmbedCaseIdRoute: ChartsCatalogEmbedCaseIdRoute,
   ApiAuthCliStatusTicketIdRoute: ApiAuthCliStatusTicketIdRoute,
+  ChartsCatalogAssetsArtifactRevisionSplatRoute:
+    ChartsCatalogAssetsArtifactRevisionSplatRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)
diff --git a/src/routes/api/github/webhook.ts b/src/routes/api/github/webhook.ts
index 0c70b4020..1cc2c19e7 100644
--- a/src/routes/api/github/webhook.ts
+++ b/src/routes/api/github/webhook.ts
@@ -1,5 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { isWatchedDocsWebhookSource } from "~/utils/docs-webhook-sources";
+import { chartsCatalogPublicationCacheTag } from "~/utils/charts-catalog";
 import {
   isRecord,
   jsonError,
@@ -161,6 +162,9 @@ export const Route = createFileRoute("/api/github/webhook")({
 
         const tags = [
           `docs-config:${repo}:${gitRef}`,
+          ...(repo === "tanstack/charts" && gitRef === "catalog-dist"
+            ? [chartsCatalogPublicationCacheTag]
+            : []),
           ...libraries
             .filter(
               (library) =>
diff --git a/src/routes/charts.catalog.all.tsx b/src/routes/charts.catalog.all.tsx
new file mode 100644
index 000000000..eed809015
--- /dev/null
+++ b/src/routes/charts.catalog.all.tsx
@@ -0,0 +1,29 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { ChartsCatalogAll } from '~/components/charts/ChartsCatalogPages'
+import { parseChartsCatalogSearch } from '~/utils/charts-catalog'
+import { getChartsCatalogAll } from '~/utils/charts-catalog.functions'
+import { seo } from '~/utils/seo'
+
+export const Route = createFileRoute('/charts/catalog/all')({
+  loader: ({ location }) =>
+    getChartsCatalogAll({
+      data: parseChartsCatalogSearch(location.searchStr),
+    }),
+  component: ChartsCatalogAllRoute,
+  head: () => ({
+    meta: seo({
+      title: 'All Charts | TanStack',
+      description: 'Every executable TanStack Charts example.',
+    }),
+  }),
+})
+
+function ChartsCatalogAllRoute() {
+  const data = Route.useLoaderData()
+  return (
+    <ChartsCatalogAll
+      artifactRevision={data.artifactRevision}
+      cases={data.cases}
+    />
+  )
+}
diff --git a/src/routes/charts.catalog.charts.$caseId.tsx b/src/routes/charts.catalog.charts.$caseId.tsx
new file mode 100644
index 000000000..46c10288b
--- /dev/null
+++ b/src/routes/charts.catalog.charts.$caseId.tsx
@@ -0,0 +1,37 @@
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { ChartsCatalogDetail } from '~/components/charts/ChartsCatalogPages'
+import { parseChartsCatalogSearch } from '~/utils/charts-catalog'
+import { getChartsCatalogCase } from '~/utils/charts-catalog.functions'
+import { seo } from '~/utils/seo'
+
+export const Route = createFileRoute('/charts/catalog/charts/$caseId')({
+  loader: async ({ location, params }) => {
+    const data = await getChartsCatalogCase({
+      data: {
+        caseId: params.caseId,
+        ...parseChartsCatalogSearch(location.searchStr),
+      },
+    })
+    if (!data) throw notFound()
+    return data
+  },
+  component: ChartsCatalogCaseRoute,
+  head: ({ loaderData }) => ({
+    meta: seo({
+      title: loaderData
+        ? `${loaderData.case.title} | TanStack Charts`
+        : 'TanStack Charts',
+      description: loaderData?.case.intent ?? 'TanStack Charts example.',
+    }),
+  }),
+})
+
+function ChartsCatalogCaseRoute() {
+  const data = Route.useLoaderData()
+  return (
+    <ChartsCatalogDetail
+      artifactRevision={data.artifactRevision}
+      catalogCase={data.case}
+    />
+  )
+}
diff --git a/src/routes/charts.catalog.index.tsx b/src/routes/charts.catalog.index.tsx
new file mode 100644
index 000000000..a1ee1198a
--- /dev/null
+++ b/src/routes/charts.catalog.index.tsx
@@ -0,0 +1,20 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { ChartsCatalogIndex } from '~/components/charts/ChartsCatalogPages'
+import { getChartsCatalogIndex } from '~/utils/charts-catalog.functions'
+import { seo } from '~/utils/seo'
+
+export const Route = createFileRoute('/charts/catalog/')({
+  loader: () => getChartsCatalogIndex(),
+  component: ChartsCatalogIndexRoute,
+  head: () => ({
+    meta: seo({
+      title: 'Charts Catalog | TanStack',
+      description: 'Executable TanStack Charts examples.',
+    }),
+  }),
+})
+
+function ChartsCatalogIndexRoute() {
+  const data = Route.useLoaderData()
+  return <ChartsCatalogIndex cases={data.cases} />
+}
diff --git a/src/routes/charts.catalog.tsx b/src/routes/charts.catalog.tsx
new file mode 100644
index 000000000..ddf0f1fd4
--- /dev/null
+++ b/src/routes/charts.catalog.tsx
@@ -0,0 +1,54 @@
+import { Link, Outlet, createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/charts/catalog')({
+  component: ChartsCatalogLayout,
+  staticData: {
+    Title: () => (
+      <Link to="/charts/catalog" className="text-gray-500 hover:text-blue-500">
+        Charts
+      </Link>
+    ),
+  },
+})
+
+function ChartsCatalogLayout() {
+  return (
+    <>
+      <nav
+        aria-label="Charts catalog"
+        className="border-b border-gray-200 dark:border-gray-800"
+      >
+        <div className="mx-auto flex max-w-[1680px] gap-5 px-4 py-3 text-sm">
+          <Link
+            to="/charts/catalog"
+            search={true}
+            activeOptions={{ exact: true }}
+            activeProps={{
+              className: 'font-semibold text-blue-600 dark:text-blue-400',
+            }}
+            inactiveProps={{
+              className:
+                'text-gray-500 hover:text-gray-950 dark:hover:text-white',
+            }}
+          >
+            Catalog
+          </Link>
+          <Link
+            to="/charts/catalog/all"
+            search={true}
+            activeProps={{
+              className: 'font-semibold text-blue-600 dark:text-blue-400',
+            }}
+            inactiveProps={{
+              className:
+                'text-gray-500 hover:text-gray-950 dark:hover:text-white',
+            }}
+          >
+            All
+          </Link>
+        </div>
+      </nav>
+      <Outlet />
+    </>
+  )
+}
diff --git a/src/routes/charts.catalog_.assets.$artifactRevision.$.ts b/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
new file mode 100644
index 000000000..b5936b74e
--- /dev/null
+++ b/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
@@ -0,0 +1,53 @@
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { parseChartsCatalogAssetRequest } from '~/utils/charts-catalog-assets'
+
+export const Route = createFileRoute(
+  '/charts/catalog_/assets/$artifactRevision/$',
+)({
+  server: {
+    handlers: {
+      GET: serveCatalogAsset,
+      HEAD: serveCatalogAsset,
+    },
+  },
+})
+
+async function serveCatalogAsset({
+  request,
+  params,
+}: {
+  request: Request
+  params: { artifactRevision: string; _splat: string }
+}) {
+  try {
+    const {
+      getChartsCatalogManifestAtRevision,
+      getVerifiedChartsCatalogAssetSource,
+    } = await import('~/utils/charts-catalog.server')
+    const manifest = await getChartsCatalogManifestAtRevision(
+      params.artifactRevision,
+    )
+    const asset = parseChartsCatalogAssetRequest({
+      artifactRevision: params.artifactRevision,
+      assetPath: params._splat,
+      manifest,
+    })
+    const descriptor = manifest.assets[asset.repoPath]
+    if (!descriptor) throw new TypeError('Unlisted Charts catalog asset')
+
+    const source = await getVerifiedChartsCatalogAssetSource(
+      params.artifactRevision,
+      asset.repoPath,
+      descriptor,
+    )
+
+    return new Response(request.method === 'HEAD' ? null : source, {
+      headers: {
+        ...asset.headers,
+        'Content-Length': String(descriptor.bytes),
+      },
+    })
+  } catch {
+    throw notFound()
+  }
+}
diff --git a/src/routes/charts.catalog_.catalog[.]json.ts b/src/routes/charts.catalog_.catalog[.]json.ts
new file mode 100644
index 000000000..6c7c3fa2b
--- /dev/null
+++ b/src/routes/charts.catalog_.catalog[.]json.ts
@@ -0,0 +1,24 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chartsCatalogPublicationCacheTag } from '~/utils/charts-catalog'
+
+export const Route = createFileRoute('/charts/catalog_/catalog.json')({
+  server: {
+    handlers: {
+      GET: async () => {
+        const { getChartsCatalogPublication } =
+          await import('~/utils/charts-catalog.server')
+        const publication = await getChartsCatalogPublication()
+
+        return Response.json(publication.manifest, {
+          headers: {
+            'Cache-Control': 'public, max-age=60, must-revalidate',
+            'Cloudflare-CDN-Cache-Control':
+              'public, max-age=300, stale-while-revalidate=300',
+            'Cache-Tag': chartsCatalogPublicationCacheTag,
+            'X-Charts-Catalog-Artifact-Revision': publication.artifactRevision,
+          },
+        })
+      },
+    },
+  },
+})
diff --git a/src/routes/charts.catalog_.embed.$caseId.tsx b/src/routes/charts.catalog_.embed.$caseId.tsx
new file mode 100644
index 000000000..521e3282a
--- /dev/null
+++ b/src/routes/charts.catalog_.embed.$caseId.tsx
@@ -0,0 +1,163 @@
+import * as React from 'react'
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { ChartsCatalogChart } from '~/components/charts/ChartsCatalogChart'
+import {
+  isChartsCatalogEmbedTheme,
+  parseChartsCatalogEmbedInteger,
+  type ChartsCatalogEmbedTheme,
+} from '~/utils/charts-catalog-embed'
+import { getChartsCatalogEmbedCase } from '~/utils/charts-catalog.functions'
+import { seo } from '~/utils/seo'
+
+export const Route = createFileRoute('/charts/catalog_/embed/$caseId')({
+  loader: async ({ location, params }) => {
+    const data = await getChartsCatalogEmbedCase({
+      data: { caseId: params.caseId },
+    })
+    if (!data) throw notFound()
+
+    const search = new URLSearchParams(location.searchStr)
+    const requestedTheme = search.get('theme')
+    return {
+      ...data,
+      height: parseChartsCatalogEmbedInteger(
+        search.get('height'),
+        360,
+        120,
+        1_200,
+      ),
+      revision: parseChartsCatalogEmbedInteger(
+        search.get('revision'),
+        0,
+        0,
+        10_000,
+      ),
+      theme: isChartsCatalogEmbedTheme(requestedTheme)
+        ? requestedTheme
+        : 'system',
+    }
+  },
+  component: ChartsCatalogEmbedRoute,
+  head: ({ loaderData }) => ({
+    meta: seo({
+      title: loaderData
+        ? `${loaderData.case.title} | TanStack Charts`
+        : 'TanStack Charts',
+      description: 'Embeddable TanStack Charts example.',
+      noindex: true,
+    }),
+  }),
+  staticData: {
+    baseParent: true,
+    showNavbar: false,
+  },
+})
+
+function ChartsCatalogEmbedRoute() {
+  const data = Route.useLoaderData()
+  const [theme, setTheme] = React.useState<ChartsCatalogEmbedTheme>(data.theme)
+  const parentOrigin = React.useMemo(resolveParentOrigin, [])
+
+  React.useEffect(() => {
+    applyEmbedTheme(theme)
+    if (theme !== 'system') return
+
+    const media = window.matchMedia('(prefers-color-scheme: dark)')
+    const update = () => applyEmbedTheme('system')
+    media.addEventListener('change', update)
+    return () => media.removeEventListener('change', update)
+  }, [theme])
+
+  React.useEffect(() => {
+    const handleMessage = (event: MessageEvent<unknown>) => {
+      if (
+        event.source !== window.parent ||
+        event.origin !== parentOrigin ||
+        !isThemeCommand(event.data, data.case.id)
+      ) {
+        return
+      }
+      setTheme(event.data.theme)
+    }
+    window.addEventListener('message', handleMessage)
+    return () => window.removeEventListener('message', handleMessage)
+  }, [data.case.id, parentOrigin])
+
+  const postStatus = React.useCallback(
+    (status: 'ready' | 'resize' | 'error') => {
+      if (window.parent === window || !parentOrigin) return
+      window.parent.postMessage(
+        {
+          type: 'tanstack-charts:embed',
+          version: 1,
+          status,
+          caseId: data.case.id,
+          height: data.height,
+        },
+        parentOrigin,
+      )
+    },
+    [data.case.id, data.height, parentOrigin],
+  )
+
+  return (
+    <main className="charts-catalog-embed overflow-hidden p-0">
+      <ChartsCatalogChart
+        artifactRevision={data.artifactRevision}
+        caseId={data.case.id}
+        height={data.height}
+        module={data.case.module}
+        onStatus={postStatus}
+        revision={data.revision}
+      />
+    </main>
+  )
+}
+
+function resolveParentOrigin() {
+  if (!document.referrer) return null
+  try {
+    const url = new URL(document.referrer)
+    return url.protocol === 'https:' || url.protocol === 'http:'
+      ? url.origin
+      : null
+  } catch {
+    return null
+  }
+}
+
+function applyEmbedTheme(theme: ChartsCatalogEmbedTheme) {
+  const dark =
+    theme === 'dark' ||
+    (theme === 'system' &&
+      window.matchMedia('(prefers-color-scheme: dark)').matches)
+  document.documentElement.classList.toggle('dark', dark)
+  document.documentElement.classList.toggle('light', !dark)
+  document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+}
+
+function isThemeCommand(
+  value: unknown,
+  caseId: string,
+): value is {
+  type: 'tanstack-charts:embed'
+  version: 1
+  command: 'set-theme'
+  caseId: string
+  theme: ChartsCatalogEmbedTheme
+} {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    value.type === 'tanstack-charts:embed' &&
+    'version' in value &&
+    value.version === 1 &&
+    'command' in value &&
+    value.command === 'set-theme' &&
+    'caseId' in value &&
+    value.caseId === caseId &&
+    'theme' in value &&
+    isChartsCatalogEmbedTheme(value.theme)
+  )
+}
diff --git a/src/server.ts b/src/server.ts
index 5de3f0f15..dbf595f4d 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -17,6 +17,7 @@ import {
   runWithRequestDiagnostics,
 } from '~/utils/prod-diagnostics.server'
 import { docsContentNegotiationVaryHeader } from '~/utils/http'
+import { isFrameEmbeddingAllowed } from '~/utils/frame-embedding'
 
 const SECURITY_HEADERS = {
   'X-Frame-Options': 'DENY',
@@ -73,7 +74,7 @@ function applyHostingHeaders(response: Response, url: URL) {
     headers.set(key, value)
   }
 
-  if (url.pathname === '/stats/npm/embed') {
+  if (isFrameEmbeddingAllowed(url.pathname)) {
     headers.delete('X-Frame-Options')
   }
 
diff --git a/src/styles/app.css b/src/styles/app.css
index 5ec2c8c77..c2a903c6e 100644
--- a/src/styles/app.css
+++ b/src/styles/app.css
@@ -1498,3 +1498,21 @@ mark {
 button[aria-label='Open TanStack Devtools'] {
   display: none !important;
 }
+
+.charts-catalog-chart {
+  --ts-chart-1: #2563eb;
+  --ts-chart-2: #f97316;
+  --ts-chart-3: #10b981;
+  --ts-chart-4: #8b5cf6;
+  --ts-chart-5: #ec4899;
+  --ts-chart-6: #06b6d4;
+}
+
+.dark .charts-catalog-chart {
+  --ts-chart-1: #6ea8fe;
+  --ts-chart-2: #ff9b65;
+  --ts-chart-3: #4fd1a1;
+  --ts-chart-4: #ae8cff;
+  --ts-chart-5: #f679bc;
+  --ts-chart-6: #4fd4e7;
+}
diff --git a/src/utils/charts-catalog-assets.ts b/src/utils/charts-catalog-assets.ts
new file mode 100644
index 000000000..70e56b72d
--- /dev/null
+++ b/src/utils/charts-catalog-assets.ts
@@ -0,0 +1,41 @@
+import { chartsCatalogRepo, type ChartsCatalogManifest } from './charts-catalog'
+
+const exactGitShaPattern = /^[a-f0-9]{40}$/
+const encodedSeparatorPattern = /%(?:2f|5c)/i
+
+export function getChartsCatalogAssetHeaders() {
+  return {
+    'Cache-Control': 'public, max-age=31536000, immutable',
+    'Cloudflare-CDN-Cache-Control': 'public, max-age=31536000, immutable',
+    'Content-Type': 'text/javascript; charset=utf-8',
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    'X-Content-Type-Options': 'nosniff',
+  }
+}
+
+export function parseChartsCatalogAssetRequest({
+  artifactRevision,
+  assetPath,
+  manifest,
+}: {
+  artifactRevision: string
+  assetPath: string
+  manifest: ChartsCatalogManifest
+}) {
+  if (
+    !exactGitShaPattern.test(artifactRevision) ||
+    encodedSeparatorPattern.test(assetPath) ||
+    assetPath.includes('\\') ||
+    assetPath.includes('..') ||
+    assetPath.startsWith('/') ||
+    !Object.hasOwn(manifest.assets, assetPath)
+  ) {
+    throw new TypeError('Invalid Charts catalog asset request')
+  }
+
+  return {
+    headers: getChartsCatalogAssetHeaders(),
+    repo: chartsCatalogRepo,
+    repoPath: assetPath,
+  }
+}
diff --git a/src/utils/charts-catalog-embed.ts b/src/utils/charts-catalog-embed.ts
new file mode 100644
index 000000000..dd9c23727
--- /dev/null
+++ b/src/utils/charts-catalog-embed.ts
@@ -0,0 +1,80 @@
+export const chartsCatalogEmbedPrefix = '/charts/catalog/embed/'
+
+export type ChartsCatalogEmbed = {
+  caseId: string
+  origin: string
+}
+
+export type ChartsCatalogEmbedTheme = 'system' | 'light' | 'dark'
+
+export function isChartsCatalogEmbedPath(pathname: string) {
+  return /^\/charts\/catalog\/embed\/[a-z0-9]+(?:-[a-z0-9]+)*\/$/.test(pathname)
+}
+
+export function parseChartsCatalogEmbed(
+  source: string | undefined,
+): ChartsCatalogEmbed | null {
+  if (!source) return null
+
+  let url: URL
+  try {
+    url = new URL(source)
+  } catch {
+    return null
+  }
+
+  if (
+    url.protocol !== 'https:' ||
+    url.hostname !== 'tanstack.com' ||
+    url.port ||
+    url.username ||
+    url.password ||
+    url.hash ||
+    !isChartsCatalogEmbedPath(url.pathname)
+  ) {
+    return null
+  }
+
+  const allowedParameters = new Set(['height', 'revision', 'theme'])
+  for (const key of url.searchParams.keys()) {
+    if (!allowedParameters.has(key)) return null
+  }
+
+  const theme = url.searchParams.get('theme')
+  if (theme !== null && !isChartsCatalogEmbedTheme(theme)) return null
+
+  const height = url.searchParams.get('height')
+  if (height !== null && !isBoundedInteger(height, 120, 1_200)) return null
+
+  const revision = url.searchParams.get('revision')
+  if (revision !== null && !isBoundedInteger(revision, 0, 10_000)) return null
+
+  return {
+    caseId: url.pathname.slice(chartsCatalogEmbedPrefix.length, -1),
+    origin: url.origin,
+  }
+}
+
+export function isChartsCatalogEmbedTheme(
+  value: unknown,
+): value is ChartsCatalogEmbedTheme {
+  return value === 'system' || value === 'light' || value === 'dark'
+}
+
+export function parseChartsCatalogEmbedInteger(
+  value: string | null,
+  fallback: number,
+  minimum: number,
+  maximum: number,
+) {
+  if (value === null || !isBoundedInteger(value, minimum, maximum)) {
+    return fallback
+  }
+  return Number(value)
+}
+
+function isBoundedInteger(value: string, minimum: number, maximum: number) {
+  if (!/^\d+$/.test(value)) return false
+  const number = Number(value)
+  return Number.isSafeInteger(number) && number >= minimum && number <= maximum
+}
diff --git a/src/utils/charts-catalog.functions.ts b/src/utils/charts-catalog.functions.ts
new file mode 100644
index 000000000..65625df16
--- /dev/null
+++ b/src/utils/charts-catalog.functions.ts
@@ -0,0 +1,157 @@
+import { createServerFn } from '@tanstack/react-start'
+import { setResponseHeader } from '@tanstack/react-start/server'
+import * as v from 'valibot'
+import type {
+  ChartsCatalogCase,
+  ChartsCatalogPublication,
+} from './charts-catalog'
+import { chartsCatalogPublicationCacheTag } from './charts-catalog'
+
+const defaultReferenceRenderer = 'observable-plot'
+
+const caseIdSchema = v.pipe(v.string(), v.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/))
+
+const comparisonInputSchema = v.strictObject({
+  comparison: v.boolean(),
+})
+
+const caseInputSchema = v.strictObject({
+  caseId: caseIdSchema,
+  comparison: v.boolean(),
+})
+
+const embedCaseInputSchema = v.strictObject({
+  caseId: caseIdSchema,
+})
+
+export const getChartsCatalogIndex = createServerFn({
+  method: 'GET',
+}).handler(async () => {
+  const publication = await loadPublication()
+  setCatalogResponseHeaders()
+  return {
+    artifactRevision: publication.artifactRevision,
+    revision: publication.manifest.revision,
+    cases: publication.manifest.cases.map(getCaseMetadata),
+  }
+})
+
+export const getChartsCatalogAll = createServerFn({ method: 'GET' })
+  .validator(comparisonInputSchema)
+  .handler(async ({ data }) => {
+    const publication = await loadPublication()
+    setCatalogResponseHeaders()
+    return {
+      artifactRevision: publication.artifactRevision,
+      revision: publication.manifest.revision,
+      cases: publication.manifest.cases.map((catalogCase) => ({
+        ...getCaseMetadata(catalogCase),
+        modules: data.comparison
+          ? catalogCase.modules
+          : { tanstack: catalogCase.modules.tanstack },
+      })),
+    }
+  })
+
+export const getChartsCatalogCase = createServerFn({ method: 'GET' })
+  .validator(caseInputSchema)
+  .handler(async ({ data }) => {
+    const publication = await loadPublication()
+    const catalogCase = publication.manifest.cases.find(
+      (entry) => entry.id === data.caseId,
+    )
+    if (!catalogCase) return null
+
+    const { getChartsCatalogSource } = await import('./charts-catalog.server')
+    const tanstackSource = await getChartsCatalogSource(
+      publication.manifest.revision,
+      catalogCase.code.tanstack,
+    )
+    const comparisonSource = data.comparison
+      ? await getChartsCatalogSource(
+          publication.manifest.revision,
+          catalogCase.code.reference,
+        )
+      : undefined
+
+    setCatalogResponseHeaders()
+    return {
+      artifactRevision: publication.artifactRevision,
+      revision: publication.manifest.revision,
+      case: {
+        ...getCaseMetadata(catalogCase),
+        modules: data.comparison
+          ? catalogCase.modules
+          : { tanstack: catalogCase.modules.tanstack },
+        code: {
+          tanstack: {
+            path: catalogCase.code.tanstack,
+            source: tanstackSource,
+          },
+          ...(data.comparison
+            ? {
+                comparison: {
+                  path: catalogCase.code.reference,
+                  source: comparisonSource,
+                },
+              }
+            : {}),
+        },
+      },
+    }
+  })
+
+export const getChartsCatalogEmbedCase = createServerFn({ method: 'GET' })
+  .validator(embedCaseInputSchema)
+  .handler(async ({ data }) => {
+    const publication = await loadPublication()
+    const catalogCase = publication.manifest.cases.find(
+      (entry) => entry.id === data.caseId,
+    )
+    if (!catalogCase) return null
+
+    setCatalogResponseHeaders()
+    return {
+      artifactRevision: publication.artifactRevision,
+      revision: publication.manifest.revision,
+      case: {
+        id: catalogCase.id,
+        title: catalogCase.title,
+        module: catalogCase.modules.tanstack,
+      },
+    }
+  })
+
+async function loadPublication(): Promise<ChartsCatalogPublication> {
+  const { getChartsCatalogPublication } =
+    await import('./charts-catalog.server')
+  return getChartsCatalogPublication()
+}
+
+function getCaseMetadata(catalogCase: ChartsCatalogCase) {
+  return {
+    schemaVersion: catalogCase.schemaVersion,
+    referenceRenderer:
+      catalogCase.referenceRenderer ?? defaultReferenceRenderer,
+    order: catalogCase.order,
+    id: catalogCase.id,
+    title: catalogCase.title,
+    family: catalogCase.family,
+    intent: catalogCase.intent,
+    support: catalogCase.support,
+    features: catalogCase.features,
+    geometry: catalogCase.geometry,
+    source: catalogCase.source,
+    ai: catalogCase.ai,
+    routes: catalogCase.routes,
+  }
+}
+
+function setCatalogResponseHeaders() {
+  setResponseHeader('Cache-Control', 'public, max-age=60, must-revalidate')
+  setResponseHeader(
+    'Cloudflare-CDN-Cache-Control',
+    'public, max-age=300, stale-while-revalidate=300',
+  )
+  setResponseHeader('Cache-Tag', chartsCatalogPublicationCacheTag)
+}
diff --git a/src/utils/charts-catalog.server.ts b/src/utils/charts-catalog.server.ts
new file mode 100644
index 000000000..2f7af581d
--- /dev/null
+++ b/src/utils/charts-catalog.server.ts
@@ -0,0 +1,131 @@
+import {
+  fetchRepoRawFile,
+  resolveGitHubRef,
+  shouldUseLocalDocsFiles,
+} from './documents.server'
+import { getCachedGitHubTextFile } from './github-content-cache.server'
+import {
+  chartsCatalogPublicationRef,
+  chartsCatalogRepo,
+  parseChartsCatalogManifest,
+  type ChartsCatalogPublication,
+} from './charts-catalog'
+
+const catalogManifestPath = 'catalog.json'
+const localCatalogRoot = '.catalog-artifact'
+const catalogHeadCachePath = '.tanstack/catalog-dist-head'
+const exactGitShaPattern = /^[a-f0-9]{40}$/
+
+export async function getChartsCatalogPublication(): Promise<ChartsCatalogPublication> {
+  if (shouldUseLocalDocsFiles()) {
+    const manifest = await readChartsCatalogManifest(
+      chartsCatalogPublicationRef,
+    )
+    return {
+      artifactRevision: manifest.revision,
+      manifest,
+    }
+  }
+
+  const artifactRevision = await resolveChartsCatalogArtifactRevision()
+  return {
+    artifactRevision,
+    manifest: await readChartsCatalogManifest(artifactRevision),
+  }
+}
+
+export async function getChartsCatalogManifestAtRevision(
+  artifactRevision: string,
+) {
+  if (!exactGitShaPattern.test(artifactRevision)) {
+    throw new TypeError('Invalid Charts catalog artifact revision')
+  }
+  return readChartsCatalogManifest(artifactRevision)
+}
+
+export async function getVerifiedChartsCatalogAssetSource(
+  artifactRevision: string,
+  assetPath: string,
+  expected: { bytes: number; sha256: string },
+) {
+  const filePath = shouldUseLocalDocsFiles()
+    ? `${localCatalogRoot}/${assetPath}`
+    : assetPath
+  const source = await fetchRepoRawFile(
+    chartsCatalogRepo,
+    artifactRevision,
+    filePath,
+  )
+
+  if (source === null) {
+    throw new Error(`Charts catalog asset not found: ${assetPath}`)
+  }
+
+  const bytes = new TextEncoder().encode(source)
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  const sha256 = Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('')
+
+  if (bytes.byteLength !== expected.bytes || sha256 !== expected.sha256) {
+    throw new Error(`Charts catalog asset failed integrity check: ${assetPath}`)
+  }
+
+  return source
+}
+
+export async function getChartsCatalogSource(
+  sourceRevision: string,
+  sourcePath: string,
+) {
+  const source = await fetchRepoRawFile(
+    chartsCatalogRepo,
+    sourceRevision,
+    sourcePath,
+  )
+  if (source === null) {
+    throw new Error(`Charts catalog source not found: ${sourcePath}`)
+  }
+  return source
+}
+
+async function readChartsCatalogManifest(artifactRevision: string) {
+  const filePath = shouldUseLocalDocsFiles()
+    ? `${localCatalogRoot}/${catalogManifestPath}`
+    : catalogManifestPath
+  const source = await fetchRepoRawFile(
+    chartsCatalogRepo,
+    artifactRevision,
+    filePath,
+  )
+
+  if (source === null) {
+    throw new Error('Charts catalog manifest is unavailable')
+  }
+
+  let value: unknown
+  try {
+    value = JSON.parse(source)
+  } catch {
+    throw new TypeError('Invalid Charts catalog manifest: expected JSON')
+  }
+  return parseChartsCatalogManifest(value)
+}
+
+async function resolveChartsCatalogArtifactRevision() {
+  const revision = await getCachedGitHubTextFile({
+    repo: chartsCatalogRepo,
+    gitRef: chartsCatalogPublicationRef,
+    path: catalogHeadCachePath,
+    origin: fetchChartsCatalogArtifactRevision,
+  })
+
+  if (!revision || !exactGitShaPattern.test(revision)) {
+    throw new Error('Charts catalog publication revision is unavailable')
+  }
+  return revision
+}
+
+async function fetchChartsCatalogArtifactRevision() {
+  return resolveGitHubRef(chartsCatalogRepo, chartsCatalogPublicationRef)
+}
diff --git a/src/utils/charts-catalog.ts b/src/utils/charts-catalog.ts
new file mode 100644
index 000000000..5472916da
--- /dev/null
+++ b/src/utils/charts-catalog.ts
@@ -0,0 +1,454 @@
+import * as v from 'valibot'
+
+export const chartsCatalogRepo = 'tanstack/charts'
+export const chartsCatalogPublicationRef = 'catalog-dist'
+export const chartsCatalogPublicationCacheTag =
+  'charts-catalog:tanstack/charts:catalog-dist'
+export const chartsCatalogBasePath = '/charts/catalog/'
+export const chartsCatalogAssetBasePath = '/charts/catalog/assets/'
+
+const gitShaSchema = v.pipe(
+  v.string(),
+  v.regex(/^[a-f0-9]{40}$/, 'Expected a lowercase 40-character Git SHA'),
+)
+
+const sha256Schema = v.pipe(
+  v.string(),
+  v.regex(/^[a-f0-9]{64}$/, 'Expected a lowercase SHA-256 digest'),
+)
+
+const caseIdSchema = v.pipe(
+  v.string(),
+  v.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Invalid catalog case ID'),
+)
+
+export const chartsCatalogAssetPathSchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^assets\/[a-zA-Z0-9][a-zA-Z0-9._-]*-[a-zA-Z0-9_-]{5,}\.js$/,
+    'Expected a flat, hashed JavaScript asset path',
+  ),
+)
+
+const sourcePathSchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^(?:benchmarks|examples)\/[a-zA-Z0-9._/-]+\.(?:ts|tsx)$/,
+    'Invalid catalog source path',
+  ),
+  v.check(
+    (path) =>
+      !path.includes('..') &&
+      !path.includes('//') &&
+      !path.includes('\\') &&
+      !path.startsWith('/'),
+    'Unsafe catalog source path',
+  ),
+)
+
+const sourceUrlSchema = v.pipe(
+  v.string(),
+  v.url(),
+  v.check((value) => {
+    const protocol = new URL(value).protocol
+    return protocol === 'https:' || protocol === 'http:'
+  }, 'Expected an HTTP source URL'),
+)
+
+const rendererSchema = v.picklist(['observable-plot', 'recharts', 'echarts'])
+
+const geometrySchema = v.strictObject({
+  role: v.pipe(v.string(), v.nonEmpty()),
+  count: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  rendererRoles: v.optional(
+    v.record(
+      v.picklist(['observable-plot', 'recharts', 'echarts', 'tanstack']),
+      v.pipe(v.string(), v.nonEmpty()),
+    ),
+  ),
+  maxCount: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+  view: v.optional(v.pipe(v.string(), v.nonEmpty())),
+  id: v.optional(v.pipe(v.string(), v.nonEmpty())),
+})
+
+const caseModuleSchema = v.strictObject({
+  path: chartsCatalogAssetPathSchema,
+  preload: v.array(chartsCatalogAssetPathSchema),
+})
+
+const comparisonModuleSchema = v.strictObject({
+  renderer: rendererSchema,
+  path: chartsCatalogAssetPathSchema,
+  preload: v.array(chartsCatalogAssetPathSchema),
+  visibility: v.literal('debug'),
+})
+
+const catalogCaseSchema = v.strictObject({
+  schemaVersion: v.literal(1),
+  referenceRenderer: v.optional(rendererSchema),
+  order: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  id: caseIdSchema,
+  title: v.pipe(v.string(), v.nonEmpty()),
+  family: v.pipe(v.string(), v.nonEmpty()),
+  intent: v.pipe(v.string(), v.nonEmpty()),
+  support: v.picklist(['native', 'composed', 'gap', 'deferred']),
+  features: v.array(v.pipe(v.string(), v.nonEmpty())),
+  geometry: v.array(geometrySchema),
+  source: v.strictObject({
+    title: v.pipe(v.string(), v.nonEmpty()),
+    url: sourceUrlSchema,
+  }),
+  ai: v.strictObject({
+    create: v.pipe(v.string(), v.nonEmpty()),
+    maintain: v.pipe(v.string(), v.nonEmpty()),
+  }),
+  routes: v.strictObject({
+    page: v.pipe(v.string(), v.nonEmpty()),
+    embed: v.pipe(v.string(), v.nonEmpty()),
+  }),
+  code: v.strictObject({
+    tanstack: sourcePathSchema,
+    reference: sourcePathSchema,
+  }),
+  modules: v.strictObject({
+    tanstack: caseModuleSchema,
+    comparison: comparisonModuleSchema,
+  }),
+  guideAssertions: v.optional(v.array(v.unknown())),
+  interactionScenarios: v.optional(v.array(v.unknown())),
+  minimumGeometrySimilarity: v.optional(
+    v.pipe(v.number(), v.minValue(0), v.maxValue(1)),
+  ),
+})
+
+const assetDescriptorSchema = v.strictObject({
+  bytes: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  sha256: sha256Schema,
+  imports: v.array(chartsCatalogAssetPathSchema),
+  dynamicImports: v.array(chartsCatalogAssetPathSchema),
+})
+
+const chartsCatalogManifestSchema = v.strictObject({
+  schemaVersion: v.literal(2),
+  revision: gitShaSchema,
+  source: v.strictObject({
+    repo: v.literal(chartsCatalogRepo),
+    ref: gitShaSchema,
+  }),
+  runtime: v.strictObject({
+    contractVersion: v.literal(1),
+    export: v.literal('mount'),
+  }),
+  site: v.strictObject({
+    origin: v.literal('https://tanstack.com'),
+    basePath: v.literal(chartsCatalogBasePath),
+    assetBasePath: v.literal(chartsCatalogAssetBasePath),
+  }),
+  embed: v.strictObject({
+    protocol: v.strictObject({
+      type: v.literal('tanstack-charts:embed'),
+      version: v.literal(1),
+      statuses: v.tuple([
+        v.literal('ready'),
+        v.literal('resize'),
+        v.literal('error'),
+      ]),
+      commands: v.tuple([v.literal('set-theme')]),
+    }),
+    parameters: v.strictObject({
+      theme: v.strictObject({
+        values: v.tuple([
+          v.literal('system'),
+          v.literal('light'),
+          v.literal('dark'),
+        ]),
+        default: v.literal('system'),
+      }),
+      height: v.strictObject({
+        minimum: v.literal(120),
+        maximum: v.literal(1_200),
+        default: v.literal(360),
+      }),
+      revision: v.strictObject({
+        minimum: v.literal(0),
+        maximum: v.literal(10_000),
+        default: v.literal(0),
+      }),
+    }),
+  }),
+  assets: v.pipe(
+    v.record(chartsCatalogAssetPathSchema, assetDescriptorSchema),
+    v.maxEntries(1_000),
+  ),
+  cases: v.pipe(v.array(catalogCaseSchema), v.nonEmpty()),
+})
+
+export type ChartsCatalogManifest = v.InferOutput<
+  typeof chartsCatalogManifestSchema
+>
+export type ChartsCatalogCase = ChartsCatalogManifest['cases'][number]
+
+export type ChartsCatalogPublication = {
+  artifactRevision: string
+  manifest: ChartsCatalogManifest
+}
+
+export function parseChartsCatalogManifest(
+  value: unknown,
+): ChartsCatalogManifest {
+  const parsed = v.safeParse(chartsCatalogManifestSchema, value)
+  if (!parsed.success) {
+    throw new TypeError(
+      `Invalid Charts catalog manifest: ${v.summarize(parsed.issues)}`,
+    )
+  }
+
+  validateManifestRelationships(parsed.output)
+  return parsed.output
+}
+
+function validateManifestRelationships(manifest: ChartsCatalogManifest) {
+  if (manifest.source.ref !== manifest.revision) {
+    throw new TypeError(
+      'Invalid Charts catalog manifest: source.ref must match revision',
+    )
+  }
+
+  const assetPaths = new Set(Object.keys(manifest.assets))
+  if (assetPaths.size === 0) {
+    throw new TypeError(
+      'Invalid Charts catalog manifest: assets must not be empty',
+    )
+  }
+
+  let totalAssetBytes = 0
+  for (const [assetPath, descriptor] of Object.entries(manifest.assets)) {
+    if (descriptor.bytes > 1024 * 1024) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: ${assetPath} exceeds 1 MiB`,
+      )
+    }
+    totalAssetBytes += descriptor.bytes
+    for (const dependency of [
+      ...descriptor.imports,
+      ...descriptor.dynamicImports,
+    ]) {
+      if (!assetPaths.has(dependency)) {
+        throw new TypeError(
+          `Invalid Charts catalog manifest: ${assetPath} references unlisted asset ${dependency}`,
+        )
+      }
+    }
+  }
+  if (totalAssetBytes > 5 * 1024 * 1024) {
+    throw new TypeError(
+      'Invalid Charts catalog manifest: assets exceed 5 MiB total',
+    )
+  }
+
+  const caseIds = new Set<string>()
+  const caseOrders = new Set<number>()
+
+  for (const catalogCase of manifest.cases) {
+    if (caseIds.has(catalogCase.id)) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: duplicate case ID ${catalogCase.id}`,
+      )
+    }
+    if (caseOrders.has(catalogCase.order)) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: duplicate case order ${catalogCase.order}`,
+      )
+    }
+    caseIds.add(catalogCase.id)
+    caseOrders.add(catalogCase.order)
+
+    const comparisonRenderer =
+      catalogCase.referenceRenderer ?? 'observable-plot'
+    const referenceFilename =
+      comparisonRenderer === 'observable-plot' ? 'plot' : comparisonRenderer
+    const sourceRoot = `benchmarks/conformance/cases/${catalogCase.id}`
+    if (
+      catalogCase.code.tanstack !== `${sourceRoot}/tanstack.ts` ||
+      catalogCase.code.reference !== `${sourceRoot}/${referenceFilename}.ts` ||
+      catalogCase.modules.comparison.renderer !== comparisonRenderer
+    ) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: source or renderer does not match case ${catalogCase.id}`,
+      )
+    }
+
+    if (
+      catalogCase.routes.page !==
+        `${chartsCatalogBasePath}charts/${catalogCase.id}/` ||
+      catalogCase.routes.embed !==
+        `${chartsCatalogBasePath}embed/${catalogCase.id}/`
+    ) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: routes do not match case ${catalogCase.id}`,
+      )
+    }
+
+    validateCaseModuleAssets(
+      catalogCase.id,
+      'tanstack',
+      catalogCase.modules.tanstack,
+      assetPaths,
+    )
+
+    validateCaseModuleAssets(
+      catalogCase.id,
+      'comparison',
+      catalogCase.modules.comparison,
+      assetPaths,
+    )
+  }
+
+  const reachableAssets = new Set<string>()
+  for (const catalogCase of manifest.cases) {
+    validateStaticPreloadClosure(
+      catalogCase.id,
+      'tanstack',
+      catalogCase.modules.tanstack,
+      manifest,
+    )
+    collectReachableAssets(
+      catalogCase.modules.tanstack.path,
+      manifest,
+      reachableAssets,
+    )
+
+    validateStaticPreloadClosure(
+      catalogCase.id,
+      'comparison',
+      catalogCase.modules.comparison,
+      manifest,
+    )
+    collectReachableAssets(
+      catalogCase.modules.comparison.path,
+      manifest,
+      reachableAssets,
+    )
+  }
+
+  for (const assetPath of assetPaths) {
+    if (!reachableAssets.has(assetPath)) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: unreferenced asset ${assetPath}`,
+      )
+    }
+  }
+}
+
+function validateCaseModuleAssets(
+  caseId: string,
+  renderer: string,
+  module: { path: string; preload: Array<string> },
+  assetPaths: Set<string>,
+) {
+  for (const assetPath of [module.path, ...module.preload]) {
+    if (!assetPaths.has(assetPath)) {
+      throw new TypeError(
+        `Invalid Charts catalog manifest: ${caseId} ${renderer} module references unlisted asset ${assetPath}`,
+      )
+    }
+  }
+}
+
+function validateStaticPreloadClosure(
+  caseId: string,
+  renderer: string,
+  module: { path: string; preload: Array<string> },
+  manifest: ChartsCatalogManifest,
+) {
+  const expectedPreload = new Set<string>()
+  collectStaticImports(module.path, manifest, expectedPreload)
+  expectedPreload.delete(module.path)
+
+  const actualPreload = new Set(module.preload)
+  if (
+    actualPreload.size !== module.preload.length ||
+    actualPreload.size !== expectedPreload.size ||
+    [...expectedPreload].some((assetPath) => !actualPreload.has(assetPath))
+  ) {
+    throw new TypeError(
+      `Invalid Charts catalog manifest: ${caseId} ${renderer} preload does not match its static import closure`,
+    )
+  }
+}
+
+function collectStaticImports(
+  assetPath: string,
+  manifest: ChartsCatalogManifest,
+  collected: Set<string>,
+) {
+  if (collected.has(assetPath)) return
+  collected.add(assetPath)
+
+  const descriptor = manifest.assets[assetPath]
+  if (!descriptor) return
+  for (const dependency of descriptor.imports) {
+    collectStaticImports(dependency, manifest, collected)
+  }
+}
+
+function collectReachableAssets(
+  assetPath: string,
+  manifest: ChartsCatalogManifest,
+  collected: Set<string>,
+) {
+  if (collected.has(assetPath)) return
+  collected.add(assetPath)
+
+  const descriptor = manifest.assets[assetPath]
+  if (!descriptor) return
+  for (const dependency of [
+    ...descriptor.imports,
+    ...descriptor.dynamicImports,
+  ]) {
+    collectReachableAssets(dependency, manifest, collected)
+  }
+}
+
+export function parseChartsCatalogSearch(
+  search: string,
+  options: { embed?: boolean } = {},
+) {
+  const parameters = new URLSearchParams(
+    search.startsWith('?') ? search.slice(1) : search,
+  )
+  const comparisonValues = parameters.getAll('compare')
+
+  return {
+    comparison:
+      options.embed !== true &&
+      comparisonValues.length === 1 &&
+      comparisonValues[0] === '1',
+  }
+}
+
+export function findChartsCatalogCase(
+  manifest: ChartsCatalogManifest,
+  caseId: string,
+) {
+  return manifest.cases.find((catalogCase) => catalogCase.id === caseId)
+}
+
+export function getChartsCatalogAssetUrl(
+  artifactRevision: string,
+  assetPath: string,
+) {
+  return `${chartsCatalogAssetBasePath}${artifactRevision}/${assetPath}`
+}
+
+export function getChartsCatalogSitemapEntries(
+  manifest: ChartsCatalogManifest,
+) {
+  return [
+    { path: '/charts/catalog/' },
+    { path: '/charts/catalog/all/' },
+    ...manifest.cases.map((catalogCase) => ({
+      path: catalogCase.routes.page,
+    })),
+  ]
+}
diff --git a/src/utils/docs-webhook-sources.ts b/src/utils/docs-webhook-sources.ts
index 3b97c3c5c..6eeff0b57 100644
--- a/src/utils/docs-webhook-sources.ts
+++ b/src/utils/docs-webhook-sources.ts
@@ -17,6 +17,11 @@ const docsWebhookSourceMap = libraries.reduce((map, library) => {
   return map
 }, new Map<string, Set<string>>())
 
+const chartsCatalogRefs =
+  docsWebhookSourceMap.get('tanstack/charts') ?? new Set<string>()
+chartsCatalogRefs.add('catalog-dist')
+docsWebhookSourceMap.set('tanstack/charts', chartsCatalogRefs)
+
 export const docsWebhookSources = Array.from(docsWebhookSourceMap.entries())
   .map(([repo, refs]) => ({
     repo,
diff --git a/src/utils/documents.server.ts b/src/utils/documents.server.ts
index c305bed5e..ca0108228 100644
--- a/src/utils/documents.server.ts
+++ b/src/utils/documents.server.ts
@@ -520,6 +520,45 @@ async function fetchRepoFileFromOrigin(
   return null
 }
 
+async function fetchRepoRawFileFromOrigin(
+  repoPair: string,
+  ref: string,
+  filepath: string,
+) {
+  const [owner, repo] = repoPair.split('/')
+  return shouldUseLocalDocsFiles()
+    ? fetchFs(repo, filepath)
+    : fetchRemote(owner, repo, ref, filepath)
+}
+
+export async function fetchRepoRawFile(
+  repoPair: string,
+  ref: string,
+  filepath: string,
+) {
+  const key = `raw:${repoPair}:${ref}:${filepath}`
+
+  if (shouldUseLocalDocsFiles()) {
+    return fetchCached({
+      key,
+      ttl: 1,
+      fn: () => fetchRepoRawFileFromOrigin(repoPair, ref, filepath),
+    })
+  }
+
+  try {
+    return await getCachedGitHubTextFile({
+      repo: repoPair,
+      gitRef: ref,
+      path: `.tanstack-raw/${filepath}`,
+      origin: () => fetchRepoRawFileFromOrigin(repoPair, ref, filepath),
+    })
+  } catch (error) {
+    if (error instanceof InvalidCacheKeyError) return null
+    throw error
+  }
+}
+
 export async function fetchRepoFile(
   repoPair: string,
   ref: string,
@@ -553,6 +592,102 @@ export async function fetchRepoFile(
   }
 }
 
+export async function resolveGitHubRef(repoPair: string, gitRef: string) {
+  if (
+    repoPair.length === 0 ||
+    repoPair.length > 100 ||
+    !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repoPair)
+  ) {
+    throw new InvalidCacheKeyError('repo', repoPair)
+  }
+  if (
+    gitRef.length === 0 ||
+    gitRef.length > 100 ||
+    !/^[a-zA-Z0-9._/-]+$/.test(gitRef) ||
+    gitRef.includes('..') ||
+    gitRef.startsWith('/') ||
+    gitRef.endsWith('/') ||
+    gitRef.includes('//')
+  ) {
+    throw new InvalidCacheKeyError('gitRef', gitRef)
+  }
+
+  const encodedRef = gitRef
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/')
+  const url = `https://api.github.com/repos/${repoPair}/git/ref/heads/${encodedRef}`
+
+  let response: Response
+  try {
+    response = await fetchWithTimeout(url, {
+      ...(await getGitHubContentFetchOptionsAsync({
+        userAgent: `docs-ref:${repoPair}`,
+      })),
+    })
+
+    if (isGitHubAuthFailureStatus(response.status)) {
+      await cancelUnusedResponseBody(response)
+      response = await fetchWithTimeout(url, {
+        ...(await getGitHubContentFetchOptionsAsync({
+          includeAuthorization: false,
+          userAgent: `docs-ref:${repoPair}`,
+        })),
+      })
+    }
+  } catch (error) {
+    throw new GitHubContentError(
+      'network',
+      `Failed to resolve ${repoPair}@${gitRef}`,
+      { cause: error },
+    )
+  }
+
+  if (!response.ok) {
+    await cancelUnusedResponseBody(response)
+    if (response.status === 404) return null
+    throw new GitHubContentError(
+      response.status === 403
+        ? 'forbidden'
+        : response.status === 429
+          ? 'rate-limit'
+          : response.status >= 500
+            ? 'server'
+            : 'invalid-response',
+      `Failed to resolve ${repoPair}@${gitRef}`,
+      { status: response.status },
+    )
+  }
+
+  let value: unknown
+  try {
+    value = await response.json()
+  } catch (error) {
+    throw new GitHubContentError(
+      'invalid-response',
+      `GitHub returned invalid JSON for ${repoPair}@${gitRef}`,
+      { cause: error },
+    )
+  }
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('object' in value) ||
+    typeof value.object !== 'object' ||
+    value.object === null ||
+    !('sha' in value.object) ||
+    typeof value.object.sha !== 'string' ||
+    !/^[a-f0-9]{40}$/.test(value.object.sha)
+  ) {
+    throw new GitHubContentError(
+      'invalid-response',
+      `GitHub returned an invalid ref for ${repoPair}@${gitRef}`,
+    )
+  }
+
+  return value.object.sha
+}
+
 export function extractFrontMatter(content: string) {
   const parsed = parseFrontMatter(content)
   const redirectFrom = normalizeRedirectFrom(parsed.data.redirect_from)
diff --git a/src/utils/frame-embedding.ts b/src/utils/frame-embedding.ts
new file mode 100644
index 000000000..1d77f0d60
--- /dev/null
+++ b/src/utils/frame-embedding.ts
@@ -0,0 +1,7 @@
+import { isChartsCatalogEmbedPath } from './charts-catalog-embed'
+
+export function isFrameEmbeddingAllowed(pathname: string) {
+  return pathname === '/stats/npm/embed' || isChartsCatalogEmbedPath(pathname)
+}
+
+export const allowsFrameEmbedding = isFrameEmbeddingAllowed
diff --git a/src/utils/sitemap.ts b/src/utils/sitemap.ts
index 42099fde5..33c389862 100644
--- a/src/utils/sitemap.ts
+++ b/src/utils/sitemap.ts
@@ -4,6 +4,7 @@ import { getPublishedPosts } from '~/utils/blog'
 import { getDocsManifest } from '~/utils/docs'
 import { getPartnerSitemapEntries } from '~/utils/partner-pages'
 import { SITE_URL } from '~/utils/site'
+import { getChartsCatalogSitemapEntries } from './charts-catalog'
 
 export type SitemapEntry = {
   path: string
@@ -109,9 +110,10 @@ export function getSiteOrigin() {
 }
 
 export async function getSitemapEntries(): Promise<Array<SitemapEntry>> {
-  const docsEntries = await Promise.all(
-    libraries.map((library) => getLibraryDocsEntries(library)),
-  )
+  const [docsEntries, chartsCatalogEntries] = await Promise.all([
+    Promise.all(libraries.map((library) => getLibraryDocsEntries(library))),
+    getPublishedChartsCatalogEntries(),
+  ])
 
   const entries = [
     ...HIGH_VALUE_NON_DOC_PAGES.map((path) => ({ path })),
@@ -119,6 +121,7 @@ export async function getSitemapEntries(): Promise<Array<SitemapEntry>> {
     ...docsEntries.flat(),
     ...getBlogEntries(),
     ...getPartnerSitemapEntries(),
+    ...chartsCatalogEntries,
   ].filter(
     (entry) =>
       entry.path !== '/intent/registry' &&
@@ -130,6 +133,20 @@ export async function getSitemapEntries(): Promise<Array<SitemapEntry>> {
   )
 }
 
+async function getPublishedChartsCatalogEntries(): Promise<
+  Array<SitemapEntry>
+> {
+  try {
+    const { getChartsCatalogPublication } =
+      await import('./charts-catalog.server')
+    const publication = await getChartsCatalogPublication()
+    return getChartsCatalogSitemapEntries(publication.manifest)
+  } catch (error) {
+    console.error('[sitemap] Charts catalog unavailable', error)
+    return [{ path: '/charts/catalog/' }]
+  }
+}
+
 export async function generateSitemapXml(origin: string) {
   const urls = (await getSitemapEntries())
     .map((entry) => {

From eea7ee4ed3e3fc9a5bb619d00683368382daea61 Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 23:14:31 -0600
Subject: [PATCH 3/9] Fix catalog search loader isolation

---
 src/routes/charts.catalog.all.tsx            | 11 ++--
 src/routes/charts.catalog.charts.$caseId.tsx | 11 ++--
 src/routes/charts.catalog_.embed.$caseId.tsx | 32 +++++-------
 src/utils/charts-catalog-embed.ts            | 51 ++++++++++++++++++-
 src/utils/charts-catalog.ts                  | 48 ++++++++++++++++--
 tests/charts-catalog-search.test.ts          | 53 +++++++++++++++++++-
 6 files changed, 173 insertions(+), 33 deletions(-)

diff --git a/src/routes/charts.catalog.all.tsx b/src/routes/charts.catalog.all.tsx
index eed809015..36d35ffe5 100644
--- a/src/routes/charts.catalog.all.tsx
+++ b/src/routes/charts.catalog.all.tsx
@@ -1,13 +1,18 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { ChartsCatalogAll } from '~/components/charts/ChartsCatalogPages'
-import { parseChartsCatalogSearch } from '~/utils/charts-catalog'
+import {
+  parseChartsCatalogRouteSearch,
+  validateChartsCatalogRouteSearch,
+} from '~/utils/charts-catalog'
 import { getChartsCatalogAll } from '~/utils/charts-catalog.functions'
 import { seo } from '~/utils/seo'
 
 export const Route = createFileRoute('/charts/catalog/all')({
-  loader: ({ location }) =>
+  validateSearch: validateChartsCatalogRouteSearch,
+  loaderDeps: ({ search }) => parseChartsCatalogRouteSearch(search),
+  loader: ({ deps }) =>
     getChartsCatalogAll({
-      data: parseChartsCatalogSearch(location.searchStr),
+      data: deps,
     }),
   component: ChartsCatalogAllRoute,
   head: () => ({
diff --git a/src/routes/charts.catalog.charts.$caseId.tsx b/src/routes/charts.catalog.charts.$caseId.tsx
index 46c10288b..da5bcfb96 100644
--- a/src/routes/charts.catalog.charts.$caseId.tsx
+++ b/src/routes/charts.catalog.charts.$caseId.tsx
@@ -1,15 +1,20 @@
 import { createFileRoute, notFound } from '@tanstack/react-router'
 import { ChartsCatalogDetail } from '~/components/charts/ChartsCatalogPages'
-import { parseChartsCatalogSearch } from '~/utils/charts-catalog'
+import {
+  parseChartsCatalogRouteSearch,
+  validateChartsCatalogRouteSearch,
+} from '~/utils/charts-catalog'
 import { getChartsCatalogCase } from '~/utils/charts-catalog.functions'
 import { seo } from '~/utils/seo'
 
 export const Route = createFileRoute('/charts/catalog/charts/$caseId')({
-  loader: async ({ location, params }) => {
+  validateSearch: validateChartsCatalogRouteSearch,
+  loaderDeps: ({ search }) => parseChartsCatalogRouteSearch(search),
+  loader: async ({ deps, params }) => {
     const data = await getChartsCatalogCase({
       data: {
         caseId: params.caseId,
-        ...parseChartsCatalogSearch(location.searchStr),
+        ...deps,
       },
     })
     if (!data) throw notFound()
diff --git a/src/routes/charts.catalog_.embed.$caseId.tsx b/src/routes/charts.catalog_.embed.$caseId.tsx
index 521e3282a..217f1e9e6 100644
--- a/src/routes/charts.catalog_.embed.$caseId.tsx
+++ b/src/routes/charts.catalog_.embed.$caseId.tsx
@@ -3,38 +3,25 @@ import { createFileRoute, notFound } from '@tanstack/react-router'
 import { ChartsCatalogChart } from '~/components/charts/ChartsCatalogChart'
 import {
   isChartsCatalogEmbedTheme,
-  parseChartsCatalogEmbedInteger,
+  parseChartsCatalogEmbedRouteSearch,
+  validateChartsCatalogEmbedRouteSearch,
   type ChartsCatalogEmbedTheme,
 } from '~/utils/charts-catalog-embed'
 import { getChartsCatalogEmbedCase } from '~/utils/charts-catalog.functions'
 import { seo } from '~/utils/seo'
 
 export const Route = createFileRoute('/charts/catalog_/embed/$caseId')({
-  loader: async ({ location, params }) => {
+  validateSearch: validateChartsCatalogEmbedRouteSearch,
+  loaderDeps: ({ search }) => parseChartsCatalogEmbedRouteSearch(search),
+  loader: async ({ deps, params }) => {
     const data = await getChartsCatalogEmbedCase({
       data: { caseId: params.caseId },
     })
     if (!data) throw notFound()
 
-    const search = new URLSearchParams(location.searchStr)
-    const requestedTheme = search.get('theme')
     return {
       ...data,
-      height: parseChartsCatalogEmbedInteger(
-        search.get('height'),
-        360,
-        120,
-        1_200,
-      ),
-      revision: parseChartsCatalogEmbedInteger(
-        search.get('revision'),
-        0,
-        0,
-        10_000,
-      ),
-      theme: isChartsCatalogEmbedTheme(requestedTheme)
-        ? requestedTheme
-        : 'system',
+      ...deps,
     }
   },
   component: ChartsCatalogEmbedRoute,
@@ -56,7 +43,11 @@ export const Route = createFileRoute('/charts/catalog_/embed/$caseId')({
 function ChartsCatalogEmbedRoute() {
   const data = Route.useLoaderData()
   const [theme, setTheme] = React.useState<ChartsCatalogEmbedTheme>(data.theme)
-  const parentOrigin = React.useMemo(resolveParentOrigin, [])
+  const [parentOrigin, setParentOrigin] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    setParentOrigin(resolveParentOrigin())
+  }, [])
 
   React.useEffect(() => {
     applyEmbedTheme(theme)
@@ -115,6 +106,7 @@ function ChartsCatalogEmbedRoute() {
 }
 
 function resolveParentOrigin() {
+  if (typeof document === 'undefined') return null
   if (!document.referrer) return null
   try {
     const url = new URL(document.referrer)
diff --git a/src/utils/charts-catalog-embed.ts b/src/utils/charts-catalog-embed.ts
index dd9c23727..2088599ed 100644
--- a/src/utils/charts-catalog-embed.ts
+++ b/src/utils/charts-catalog-embed.ts
@@ -7,6 +7,18 @@ export type ChartsCatalogEmbed = {
 
 export type ChartsCatalogEmbedTheme = 'system' | 'light' | 'dark'
 
+export type ChartsCatalogEmbedLoaderDeps = {
+  height: number
+  revision: number
+  theme: ChartsCatalogEmbedTheme
+}
+
+export type ChartsCatalogEmbedRouteSearch = {
+  height?: string | Array<string>
+  revision?: string | Array<string>
+  theme?: string | Array<string>
+}
+
 export function isChartsCatalogEmbedPath(pathname: string) {
   return /^\/charts\/catalog\/embed\/[a-z0-9]+(?:-[a-z0-9]+)*\/$/.test(pathname)
 }
@@ -62,19 +74,54 @@ export function isChartsCatalogEmbedTheme(
 }
 
 export function parseChartsCatalogEmbedInteger(
-  value: string | null,
+  value: unknown,
   fallback: number,
   minimum: number,
   maximum: number,
 ) {
-  if (value === null || !isBoundedInteger(value, minimum, maximum)) {
+  if (typeof value !== 'string' || !isBoundedInteger(value, minimum, maximum)) {
     return fallback
   }
   return Number(value)
 }
 
+export function validateChartsCatalogEmbedRouteSearch(
+  search: Record<string, unknown>,
+): ChartsCatalogEmbedRouteSearch {
+  const height = getChartsCatalogEmbedRouteSearchValue(search.height)
+  const revision = getChartsCatalogEmbedRouteSearchValue(search.revision)
+  const theme = getChartsCatalogEmbedRouteSearchValue(search.theme)
+
+  return {
+    ...(height === undefined ? {} : { height }),
+    ...(revision === undefined ? {} : { revision }),
+    ...(theme === undefined ? {} : { theme }),
+  }
+}
+
+export function parseChartsCatalogEmbedRouteSearch(
+  search: ChartsCatalogEmbedRouteSearch,
+): ChartsCatalogEmbedLoaderDeps {
+  return {
+    height: parseChartsCatalogEmbedInteger(search.height, 360, 120, 1_200),
+    revision: parseChartsCatalogEmbedInteger(search.revision, 0, 0, 10_000),
+    theme: isChartsCatalogEmbedTheme(search.theme) ? search.theme : 'system',
+  }
+}
+
 function isBoundedInteger(value: string, minimum: number, maximum: number) {
   if (!/^\d+$/.test(value)) return false
   const number = Number(value)
   return Number.isSafeInteger(number) && number >= minimum && number <= maximum
 }
+
+function getChartsCatalogEmbedRouteSearchValue(value: unknown) {
+  if (typeof value === 'string') return value
+  if (
+    Array.isArray(value) &&
+    value.every((entry): entry is string => typeof entry === 'string')
+  ) {
+    return value
+  }
+  return undefined
+}
diff --git a/src/utils/charts-catalog.ts b/src/utils/charts-catalog.ts
index 5472916da..c08f313e5 100644
--- a/src/utils/charts-catalog.ts
+++ b/src/utils/charts-catalog.ts
@@ -420,13 +420,53 @@ export function parseChartsCatalogSearch(
   const comparisonValues = parameters.getAll('compare')
 
   return {
-    comparison:
-      options.embed !== true &&
-      comparisonValues.length === 1 &&
-      comparisonValues[0] === '1',
+    comparison: isChartsCatalogComparisonEnabled(comparisonValues, options),
   }
 }
 
+export type ChartsCatalogRouteSearch = {
+  compare?: string | Array<string>
+}
+
+export function validateChartsCatalogRouteSearch(
+  search: Record<string, unknown>,
+): ChartsCatalogRouteSearch {
+  const compare = search.compare
+  if (typeof compare === 'string') return { compare }
+  if (
+    Array.isArray(compare) &&
+    compare.every((value): value is string => typeof value === 'string')
+  ) {
+    return { compare }
+  }
+  return {}
+}
+
+export function parseChartsCatalogRouteSearch(
+  search: ChartsCatalogRouteSearch,
+  options: { embed?: boolean } = {},
+) {
+  const comparisonValues =
+    typeof search.compare === 'string'
+      ? [search.compare]
+      : (search.compare ?? [])
+
+  return {
+    comparison: isChartsCatalogComparisonEnabled(comparisonValues, options),
+  }
+}
+
+function isChartsCatalogComparisonEnabled(
+  comparisonValues: Array<string>,
+  options: { embed?: boolean },
+) {
+  return (
+    options.embed !== true &&
+    comparisonValues.length === 1 &&
+    comparisonValues[0] === '1'
+  )
+}
+
 export function findChartsCatalogCase(
   manifest: ChartsCatalogManifest,
   caseId: string,
diff --git a/tests/charts-catalog-search.test.ts b/tests/charts-catalog-search.test.ts
index 8edf20aa6..9c37f8c53 100644
--- a/tests/charts-catalog-search.test.ts
+++ b/tests/charts-catalog-search.test.ts
@@ -1,6 +1,14 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
-import { parseChartsCatalogSearch } from '../src/utils/charts-catalog'
+import {
+  parseChartsCatalogRouteSearch,
+  parseChartsCatalogSearch,
+  validateChartsCatalogRouteSearch,
+} from '../src/utils/charts-catalog'
+import {
+  parseChartsCatalogEmbedRouteSearch,
+  validateChartsCatalogEmbedRouteSearch,
+} from '../src/utils/charts-catalog-embed'
 
 test('catalog comparison mode requires one exact compare=1 parameter', () => {
   for (const search of ['?compare=1', 'compare=1', '?view=all&compare=1']) {
@@ -38,3 +46,46 @@ test('catalog embeds never enable comparison modules', () => {
     false,
   )
 })
+
+test('validated catalog search preserves exact comparison loader deps', () => {
+  for (const value of ['1', ['1']]) {
+    const search = validateChartsCatalogRouteSearch({ compare: value })
+    assert.equal(parseChartsCatalogRouteSearch(search).comparison, true)
+  }
+
+  for (const value of [undefined, '', '0', 'true', ['1', '1'], ['0', '1'], 1]) {
+    const search = validateChartsCatalogRouteSearch({ compare: value })
+    assert.equal(parseChartsCatalogRouteSearch(search).comparison, false)
+  }
+})
+
+test('validated embed search produces stable loader deps', () => {
+  assert.deepEqual(
+    parseChartsCatalogEmbedRouteSearch(
+      validateChartsCatalogEmbedRouteSearch({
+        height: '420',
+        revision: '3',
+        theme: 'dark',
+      }),
+    ),
+    {
+      height: 420,
+      revision: 3,
+      theme: 'dark',
+    },
+  )
+  assert.deepEqual(
+    parseChartsCatalogEmbedRouteSearch(
+      validateChartsCatalogEmbedRouteSearch({
+        height: ['420', '421'],
+        revision: '-1',
+        theme: ['dark'],
+      }),
+    ),
+    {
+      height: 360,
+      revision: 0,
+      theme: 'system',
+    },
+  )
+})

From cf3baa84ba7c04bc7940c44646745164114d81db Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 23:18:33 -0600
Subject: [PATCH 4/9] Handle decoded catalog search values

---
 src/utils/charts-catalog-embed.ts   | 21 ++++++++++++++++-----
 src/utils/charts-catalog.ts         | 23 +++++++++++++++++------
 tests/charts-catalog-search.test.ts | 18 ++++++++++++++----
 3 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/src/utils/charts-catalog-embed.ts b/src/utils/charts-catalog-embed.ts
index 2088599ed..70a9b696d 100644
--- a/src/utils/charts-catalog-embed.ts
+++ b/src/utils/charts-catalog-embed.ts
@@ -14,9 +14,9 @@ export type ChartsCatalogEmbedLoaderDeps = {
 }
 
 export type ChartsCatalogEmbedRouteSearch = {
-  height?: string | Array<string>
-  revision?: string | Array<string>
-  theme?: string | Array<string>
+  height?: string | number | Array<string | number>
+  revision?: string | number | Array<string | number>
+  theme?: string | number | Array<string | number>
 }
 
 export function isChartsCatalogEmbedPath(pathname: string) {
@@ -79,6 +79,14 @@ export function parseChartsCatalogEmbedInteger(
   minimum: number,
   maximum: number,
 ) {
+  if (
+    typeof value === 'number' &&
+    Number.isSafeInteger(value) &&
+    value >= minimum &&
+    value <= maximum
+  ) {
+    return value
+  }
   if (typeof value !== 'string' || !isBoundedInteger(value, minimum, maximum)) {
     return fallback
   }
@@ -116,10 +124,13 @@ function isBoundedInteger(value: string, minimum: number, maximum: number) {
 }
 
 function getChartsCatalogEmbedRouteSearchValue(value: unknown) {
-  if (typeof value === 'string') return value
+  if (typeof value === 'string' || typeof value === 'number') return value
   if (
     Array.isArray(value) &&
-    value.every((entry): entry is string => typeof entry === 'string')
+    value.every(
+      (entry): entry is string | number =>
+        typeof entry === 'string' || typeof entry === 'number',
+    )
   ) {
     return value
   }
diff --git a/src/utils/charts-catalog.ts b/src/utils/charts-catalog.ts
index c08f313e5..33632d9c6 100644
--- a/src/utils/charts-catalog.ts
+++ b/src/utils/charts-catalog.ts
@@ -425,17 +425,28 @@ export function parseChartsCatalogSearch(
 }
 
 export type ChartsCatalogRouteSearch = {
-  compare?: string | Array<string>
+  compare?: string | number | boolean | Array<string | number | boolean>
 }
 
 export function validateChartsCatalogRouteSearch(
   search: Record<string, unknown>,
 ): ChartsCatalogRouteSearch {
   const compare = search.compare
-  if (typeof compare === 'string') return { compare }
+  if (
+    typeof compare === 'string' ||
+    typeof compare === 'number' ||
+    typeof compare === 'boolean'
+  ) {
+    return { compare }
+  }
   if (
     Array.isArray(compare) &&
-    compare.every((value): value is string => typeof value === 'string')
+    compare.every(
+      (value): value is string | number | boolean =>
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean',
+    )
   ) {
     return { compare }
   }
@@ -447,7 +458,7 @@ export function parseChartsCatalogRouteSearch(
   options: { embed?: boolean } = {},
 ) {
   const comparisonValues =
-    typeof search.compare === 'string'
+    !Array.isArray(search.compare) && search.compare !== undefined
       ? [search.compare]
       : (search.compare ?? [])
 
@@ -457,13 +468,13 @@ export function parseChartsCatalogRouteSearch(
 }
 
 function isChartsCatalogComparisonEnabled(
-  comparisonValues: Array<string>,
+  comparisonValues: Array<string | number | boolean>,
   options: { embed?: boolean },
 ) {
   return (
     options.embed !== true &&
     comparisonValues.length === 1 &&
-    comparisonValues[0] === '1'
+    (comparisonValues[0] === '1' || comparisonValues[0] === 1)
   )
 }
 
diff --git a/tests/charts-catalog-search.test.ts b/tests/charts-catalog-search.test.ts
index 9c37f8c53..e59499a23 100644
--- a/tests/charts-catalog-search.test.ts
+++ b/tests/charts-catalog-search.test.ts
@@ -48,12 +48,22 @@ test('catalog embeds never enable comparison modules', () => {
 })
 
 test('validated catalog search preserves exact comparison loader deps', () => {
-  for (const value of ['1', ['1']]) {
+  for (const value of ['1', 1, ['1'], [1]]) {
     const search = validateChartsCatalogRouteSearch({ compare: value })
     assert.equal(parseChartsCatalogRouteSearch(search).comparison, true)
   }
 
-  for (const value of [undefined, '', '0', 'true', ['1', '1'], ['0', '1'], 1]) {
+  for (const value of [
+    undefined,
+    '',
+    '0',
+    'true',
+    true,
+    1.1,
+    ['1', '1'],
+    [1, 1],
+    ['0', '1'],
+  ]) {
     const search = validateChartsCatalogRouteSearch({ compare: value })
     assert.equal(parseChartsCatalogRouteSearch(search).comparison, false)
   }
@@ -63,8 +73,8 @@ test('validated embed search produces stable loader deps', () => {
   assert.deepEqual(
     parseChartsCatalogEmbedRouteSearch(
       validateChartsCatalogEmbedRouteSearch({
-        height: '420',
-        revision: '3',
+        height: 420,
+        revision: 3,
         theme: 'dark',
       }),
     ),

From 796f20e15749dbd5ee3351456529eb47e819f6a9 Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 23:34:45 -0600
Subject: [PATCH 5/9] Address Charts catalog review findings

---
 src/components/charts/ChartsCatalogChart.tsx  | 58 +++++++------
 src/components/charts/ChartsCatalogPages.tsx  |  2 +-
 ...rts.catalog_.assets.$artifactRevision.$.ts | 82 +++++++++++++++----
 src/routes/charts.catalog_.catalog[.]json.ts  |  7 +-
 src/utils/charts-catalog-embed.ts             | 12 ++-
 src/utils/charts-catalog.functions.ts         | 44 +++++-----
 src/utils/charts-catalog.server.ts            | 64 +++++++++++++--
 src/utils/charts-catalog.ts                   | 30 +++++--
 src/utils/documents.server.ts                 | 53 ++++++++----
 tests/charts-catalog-assets.test.ts           | 35 ++++++++
 tests/charts-catalog-manifest.test.ts         |  4 +
 tests/charts-catalog-raw-content.test.ts      | 39 ++++++++-
 tests/charts-catalog-site-contracts.test.ts   | 10 +++
 13 files changed, 336 insertions(+), 104 deletions(-)

diff --git a/src/components/charts/ChartsCatalogChart.tsx b/src/components/charts/ChartsCatalogChart.tsx
index 400e335bd..bbfca1e2a 100644
--- a/src/components/charts/ChartsCatalogChart.tsx
+++ b/src/components/charts/ChartsCatalogChart.tsx
@@ -42,9 +42,15 @@ export function ChartsCatalogChart({
   revision?: number
 }) {
   const containerRef = React.useRef<HTMLDivElement>(null)
+  const handleRef = React.useRef<ChartMountHandle | undefined>(undefined)
+  const inputRef = React.useRef({ height, interactive, revision })
+  const onStatusRef = React.useRef(onStatus)
   const [visible, setVisible] = React.useState(!defer)
   const [failed, setFailed] = React.useState(false)
 
+  inputRef.current = { height, interactive, revision }
+  onStatusRef.current = onStatus
+
   React.useEffect(() => {
     const container = containerRef.current
     if (!defer || visible || !container) return
@@ -71,7 +77,7 @@ export function ChartsCatalogChart({
     if (!container || !visible) return
 
     let cancelled = false
-    let handle: ChartMountHandle | undefined
+    let mountedHandle: ChartMountHandle | undefined
     let width = measureWidth(container)
     const preloadLinks = module.preload.map((assetPath) => {
       const link = document.createElement('link')
@@ -95,54 +101,60 @@ export function ChartsCatalogChart({
 
         const mounted = loaded.mount(container, {
           width,
-          height,
-          revision,
-          interactive,
+          ...inputRef.current,
         })
         if (!isChartMountHandle(mounted)) {
           throw new TypeError('Invalid Charts catalog mount handle')
         }
-        handle = mounted
-        requestAnimationFrame(() => onStatus?.('ready'))
+        mountedHandle = mounted
+        handleRef.current = mounted
+        requestAnimationFrame(() => {
+          if (!cancelled) onStatusRef.current?.('ready')
+        })
       })
       .catch((error: unknown) => {
         if (cancelled) return
         console.error(`Unable to mount Charts catalog case ${caseId}`, error)
         setFailed(true)
-        onStatus?.('error')
+        onStatusRef.current?.('error')
       })
 
     const resizeObserver = new ResizeObserver(() => {
       const nextWidth = measureWidth(container)
       if (nextWidth === width || nextWidth < 1) return
       width = nextWidth
-      handle?.update({
+      handleRef.current?.update({
         width,
-        height,
-        revision,
-        interactive,
+        ...inputRef.current,
       })
-      onStatus?.('resize')
+      onStatusRef.current?.('resize')
     })
     resizeObserver.observe(container)
 
     return () => {
       cancelled = true
       resizeObserver.disconnect()
-      handle?.destroy()
+      mountedHandle?.destroy()
+      if (handleRef.current === mountedHandle) {
+        handleRef.current = undefined
+      }
       for (const link of preloadLinks) link.remove()
       container.replaceChildren()
     }
-  }, [
-    artifactRevision,
-    caseId,
-    height,
-    interactive,
-    module,
-    onStatus,
-    revision,
-    visible,
-  ])
+  }, [artifactRevision, caseId, module, visible])
+
+  React.useEffect(() => {
+    const container = containerRef.current
+    const handle = handleRef.current
+    if (!container || !handle) return
+
+    handle.update({
+      width: measureWidth(container),
+      height,
+      interactive,
+      revision,
+    })
+  }, [height, interactive, revision])
 
   return (
     <div
diff --git a/src/components/charts/ChartsCatalogPages.tsx b/src/components/charts/ChartsCatalogPages.tsx
index 781476cee..9c0de5bd1 100644
--- a/src/components/charts/ChartsCatalogPages.tsx
+++ b/src/components/charts/ChartsCatalogPages.tsx
@@ -247,7 +247,7 @@ export function ChartsCatalogDetail({
 
       <div
         className={`mx-auto grid gap-6 ${comparison ? 'xl:grid-cols-2' : ''} ${
-          width === 'compact' ? 'max-w-2xl' : ''
+          width === 'compact' ? 'max-w-[640px]' : 'max-w-[960px]'
         }`}
       >
         <ChartPanel label="TanStack">
diff --git a/src/routes/charts.catalog_.assets.$artifactRevision.$.ts b/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
index b5936b74e..114d9b7ca 100644
--- a/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
+++ b/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
@@ -19,35 +19,83 @@ async function serveCatalogAsset({
   request: Request
   params: { artifactRevision: string; _splat: string }
 }) {
+  const {
+    classifyChartsCatalogAssetError,
+    getChartsCatalogManifestAtRevision,
+    getVerifiedChartsCatalogAssetSource,
+  } = await import('~/utils/charts-catalog.server')
+
+  let manifest: Awaited<ReturnType<typeof getChartsCatalogManifestAtRevision>>
   try {
-    const {
-      getChartsCatalogManifestAtRevision,
-      getVerifiedChartsCatalogAssetSource,
-    } = await import('~/utils/charts-catalog.server')
-    const manifest = await getChartsCatalogManifestAtRevision(
-      params.artifactRevision,
+    manifest = await getChartsCatalogManifestAtRevision(params.artifactRevision)
+  } catch (error) {
+    return handleCatalogAssetError(
+      error,
+      classifyChartsCatalogAssetError,
+      request.method,
     )
-    const asset = parseChartsCatalogAssetRequest({
+  }
+
+  let asset: ReturnType<typeof parseChartsCatalogAssetRequest>
+  try {
+    asset = parseChartsCatalogAssetRequest({
       artifactRevision: params.artifactRevision,
       assetPath: params._splat,
       manifest,
     })
-    const descriptor = manifest.assets[asset.repoPath]
-    if (!descriptor) throw new TypeError('Unlisted Charts catalog asset')
+  } catch (error) {
+    if (error instanceof TypeError) throw notFound()
+    throw error
+  }
+
+  const descriptor = manifest.assets[asset.repoPath]
+  if (!descriptor) throw notFound()
 
-    const source = await getVerifiedChartsCatalogAssetSource(
+  let source: string
+  try {
+    source = await getVerifiedChartsCatalogAssetSource(
       params.artifactRevision,
       asset.repoPath,
       descriptor,
     )
+  } catch (error) {
+    return handleCatalogAssetError(
+      error,
+      classifyChartsCatalogAssetError,
+      request.method,
+    )
+  }
+
+  return new Response(request.method === 'HEAD' ? null : source, {
+    headers: {
+      ...asset.headers,
+      'Content-Length': String(descriptor.bytes),
+    },
+  })
+}
 
-    return new Response(request.method === 'HEAD' ? null : source, {
-      headers: {
-        ...asset.headers,
-        'Content-Length': String(descriptor.bytes),
+function handleCatalogAssetError(
+  error: unknown,
+  classify: (error: unknown) => 'not-found' | 'unavailable' | 'internal',
+  method: string,
+) {
+  const classification = classify(error)
+  if (classification === 'not-found') throw notFound()
+
+  console.error('[Charts catalog asset] Failed to serve asset', error)
+  if (classification === 'unavailable') {
+    return new Response(
+      method === 'HEAD' ? null : 'Charts catalog asset temporarily unavailable',
+      {
+        status: 503,
+        headers: {
+          'Cache-Control': 'no-store',
+          'Cloudflare-CDN-Cache-Control': 'no-store',
+          'Retry-After': '60',
+        },
       },
-    })
-  } catch {
-    throw notFound()
+    )
   }
+
+  throw error
 }
diff --git a/src/routes/charts.catalog_.catalog[.]json.ts b/src/routes/charts.catalog_.catalog[.]json.ts
index 6c7c3fa2b..dfd18c171 100644
--- a/src/routes/charts.catalog_.catalog[.]json.ts
+++ b/src/routes/charts.catalog_.catalog[.]json.ts
@@ -1,5 +1,5 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { chartsCatalogPublicationCacheTag } from '~/utils/charts-catalog'
+import { chartsCatalogPublicationCacheHeaders } from '~/utils/charts-catalog'
 
 export const Route = createFileRoute('/charts/catalog_/catalog.json')({
   server: {
@@ -11,10 +11,7 @@ export const Route = createFileRoute('/charts/catalog_/catalog.json')({
 
         return Response.json(publication.manifest, {
           headers: {
-            'Cache-Control': 'public, max-age=60, must-revalidate',
-            'Cloudflare-CDN-Cache-Control':
-              'public, max-age=300, stale-while-revalidate=300',
-            'Cache-Tag': chartsCatalogPublicationCacheTag,
+            ...chartsCatalogPublicationCacheHeaders,
             'X-Charts-Catalog-Artifact-Revision': publication.artifactRevision,
           },
         })
diff --git a/src/utils/charts-catalog-embed.ts b/src/utils/charts-catalog-embed.ts
index 70a9b696d..1be41b900 100644
--- a/src/utils/charts-catalog-embed.ts
+++ b/src/utils/charts-catalog-embed.ts
@@ -1,3 +1,5 @@
+import { isChartsCatalogCaseId } from './charts-catalog'
+
 export const chartsCatalogEmbedPrefix = '/charts/catalog/embed/'
 
 export type ChartsCatalogEmbed = {
@@ -20,7 +22,15 @@ export type ChartsCatalogEmbedRouteSearch = {
 }
 
 export function isChartsCatalogEmbedPath(pathname: string) {
-  return /^\/charts\/catalog\/embed\/[a-z0-9]+(?:-[a-z0-9]+)*\/$/.test(pathname)
+  if (
+    !pathname.startsWith(chartsCatalogEmbedPrefix) ||
+    !pathname.endsWith('/')
+  ) {
+    return false
+  }
+  return isChartsCatalogCaseId(
+    pathname.slice(chartsCatalogEmbedPrefix.length, -1),
+  )
 }
 
 export function parseChartsCatalogEmbed(
diff --git a/src/utils/charts-catalog.functions.ts b/src/utils/charts-catalog.functions.ts
index 65625df16..d40e0caf3 100644
--- a/src/utils/charts-catalog.functions.ts
+++ b/src/utils/charts-catalog.functions.ts
@@ -5,23 +5,24 @@ import type {
   ChartsCatalogCase,
   ChartsCatalogPublication,
 } from './charts-catalog'
-import { chartsCatalogPublicationCacheTag } from './charts-catalog'
+import {
+  chartsCatalogCaseIdSchema,
+  chartsCatalogPublicationCacheHeaders,
+} from './charts-catalog'
 
 const defaultReferenceRenderer = 'observable-plot'
 
-const caseIdSchema = v.pipe(v.string(), v.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/))
-
 const comparisonInputSchema = v.strictObject({
   comparison: v.boolean(),
 })
 
 const caseInputSchema = v.strictObject({
-  caseId: caseIdSchema,
+  caseId: chartsCatalogCaseIdSchema,
   comparison: v.boolean(),
 })
 
 const embedCaseInputSchema = v.strictObject({
-  caseId: caseIdSchema,
+  caseId: chartsCatalogCaseIdSchema,
 })
 
 export const getChartsCatalogIndex = createServerFn({
@@ -63,16 +64,18 @@ export const getChartsCatalogCase = createServerFn({ method: 'GET' })
     if (!catalogCase) return null
 
     const { getChartsCatalogSource } = await import('./charts-catalog.server')
-    const tanstackSource = await getChartsCatalogSource(
-      publication.manifest.revision,
-      catalogCase.code.tanstack,
-    )
-    const comparisonSource = data.comparison
-      ? await getChartsCatalogSource(
-          publication.manifest.revision,
-          catalogCase.code.reference,
-        )
-      : undefined
+    const [tanstackSource, comparisonSource] = await Promise.all([
+      getChartsCatalogSource(
+        publication.manifest.revision,
+        catalogCase.code.tanstack,
+      ),
+      data.comparison
+        ? getChartsCatalogSource(
+            publication.manifest.revision,
+            catalogCase.code.reference,
+          )
+        : Promise.resolve(undefined),
+    ])
 
     setCatalogResponseHeaders()
     return {
@@ -148,10 +151,9 @@ function getCaseMetadata(catalogCase: ChartsCatalogCase) {
 }
 
 function setCatalogResponseHeaders() {
-  setResponseHeader('Cache-Control', 'public, max-age=60, must-revalidate')
-  setResponseHeader(
-    'Cloudflare-CDN-Cache-Control',
-    'public, max-age=300, stale-while-revalidate=300',
-  )
-  setResponseHeader('Cache-Tag', chartsCatalogPublicationCacheTag)
+  for (const [name, value] of Object.entries(
+    chartsCatalogPublicationCacheHeaders,
+  )) {
+    setResponseHeader(name, value)
+  }
 }
diff --git a/src/utils/charts-catalog.server.ts b/src/utils/charts-catalog.server.ts
index 2f7af581d..3a0af5a47 100644
--- a/src/utils/charts-catalog.server.ts
+++ b/src/utils/charts-catalog.server.ts
@@ -1,5 +1,6 @@
 import {
   fetchRepoRawFile,
+  GitHubContentError,
   resolveGitHubRef,
   shouldUseLocalDocsFiles,
 } from './documents.server'
@@ -16,6 +17,33 @@ const localCatalogRoot = '.catalog-artifact'
 const catalogHeadCachePath = '.tanstack/catalog-dist-head'
 const exactGitShaPattern = /^[a-f0-9]{40}$/
 
+export class ChartsCatalogResourceNotFoundError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ChartsCatalogResourceNotFoundError'
+  }
+}
+
+export class ChartsCatalogIntegrityError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause })
+    this.name = 'ChartsCatalogIntegrityError'
+  }
+}
+
+export function classifyChartsCatalogAssetError(error: unknown) {
+  if (error instanceof ChartsCatalogResourceNotFoundError) {
+    return 'not-found'
+  }
+  if (
+    error instanceof GitHubContentError &&
+    ['network', 'rate-limit', 'server'].includes(error.kind)
+  ) {
+    return 'unavailable'
+  }
+  return 'internal'
+}
+
 export async function getChartsCatalogPublication(): Promise<ChartsCatalogPublication> {
   if (shouldUseLocalDocsFiles()) {
     const manifest = await readChartsCatalogManifest(
@@ -38,7 +66,9 @@ export async function getChartsCatalogManifestAtRevision(
   artifactRevision: string,
 ) {
   if (!exactGitShaPattern.test(artifactRevision)) {
-    throw new TypeError('Invalid Charts catalog artifact revision')
+    throw new ChartsCatalogResourceNotFoundError(
+      'Invalid Charts catalog artifact revision',
+    )
   }
   return readChartsCatalogManifest(artifactRevision)
 }
@@ -58,7 +88,9 @@ export async function getVerifiedChartsCatalogAssetSource(
   )
 
   if (source === null) {
-    throw new Error(`Charts catalog asset not found: ${assetPath}`)
+    throw new ChartsCatalogResourceNotFoundError(
+      `Charts catalog asset not found: ${assetPath}`,
+    )
   }
 
   const bytes = new TextEncoder().encode(source)
@@ -68,7 +100,9 @@ export async function getVerifiedChartsCatalogAssetSource(
   ).join('')
 
   if (bytes.byteLength !== expected.bytes || sha256 !== expected.sha256) {
-    throw new Error(`Charts catalog asset failed integrity check: ${assetPath}`)
+    throw new ChartsCatalogIntegrityError(
+      `Charts catalog asset failed integrity check: ${assetPath}`,
+    )
   }
 
   return source
@@ -84,7 +118,9 @@ export async function getChartsCatalogSource(
     sourcePath,
   )
   if (source === null) {
-    throw new Error(`Charts catalog source not found: ${sourcePath}`)
+    throw new ChartsCatalogResourceNotFoundError(
+      `Charts catalog source not found: ${sourcePath}`,
+    )
   }
   return source
 }
@@ -100,16 +136,28 @@ async function readChartsCatalogManifest(artifactRevision: string) {
   )
 
   if (source === null) {
-    throw new Error('Charts catalog manifest is unavailable')
+    throw new ChartsCatalogResourceNotFoundError(
+      'Charts catalog manifest is unavailable',
+    )
   }
 
   let value: unknown
   try {
     value = JSON.parse(source)
-  } catch {
-    throw new TypeError('Invalid Charts catalog manifest: expected JSON')
+  } catch (error) {
+    throw new ChartsCatalogIntegrityError(
+      'Invalid Charts catalog manifest: expected JSON',
+      error,
+    )
+  }
+  try {
+    return parseChartsCatalogManifest(value)
+  } catch (error) {
+    throw new ChartsCatalogIntegrityError(
+      'Invalid Charts catalog manifest contract',
+      error,
+    )
   }
-  return parseChartsCatalogManifest(value)
 }
 
 async function resolveChartsCatalogArtifactRevision() {
diff --git a/src/utils/charts-catalog.ts b/src/utils/charts-catalog.ts
index 33632d9c6..beb404b58 100644
--- a/src/utils/charts-catalog.ts
+++ b/src/utils/charts-catalog.ts
@@ -6,6 +6,12 @@ export const chartsCatalogPublicationCacheTag =
   'charts-catalog:tanstack/charts:catalog-dist'
 export const chartsCatalogBasePath = '/charts/catalog/'
 export const chartsCatalogAssetBasePath = '/charts/catalog/assets/'
+export const chartsCatalogPublicationCacheHeaders = {
+  'Cache-Control': 'public, max-age=60, must-revalidate',
+  'Cloudflare-CDN-Cache-Control':
+    'public, max-age=300, stale-while-revalidate=300',
+  'Cache-Tag': chartsCatalogPublicationCacheTag,
+}
 
 const gitShaSchema = v.pipe(
   v.string(),
@@ -17,11 +23,17 @@ const sha256Schema = v.pipe(
   v.regex(/^[a-f0-9]{64}$/, 'Expected a lowercase SHA-256 digest'),
 )
 
-const caseIdSchema = v.pipe(
+const chartsCatalogCaseIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export const chartsCatalogCaseIdSchema = v.pipe(
   v.string(),
-  v.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Invalid catalog case ID'),
+  v.regex(chartsCatalogCaseIdPattern, 'Invalid catalog case ID'),
 )
 
+export function isChartsCatalogCaseId(value: string) {
+  return chartsCatalogCaseIdPattern.test(value)
+}
+
 export const chartsCatalogAssetPathSchema = v.pipe(
   v.string(),
   v.regex(
@@ -49,10 +61,10 @@ const sourcePathSchema = v.pipe(
 const sourceUrlSchema = v.pipe(
   v.string(),
   v.url(),
-  v.check((value) => {
-    const protocol = new URL(value).protocol
-    return protocol === 'https:' || protocol === 'http:'
-  }, 'Expected an HTTP source URL'),
+  v.check(
+    (value) => new URL(value).protocol === 'https:',
+    'Expected an HTTPS source URL',
+  ),
 )
 
 const rendererSchema = v.picklist(['observable-plot', 'recharts', 'echarts'])
@@ -87,7 +99,7 @@ const catalogCaseSchema = v.strictObject({
   schemaVersion: v.literal(1),
   referenceRenderer: v.optional(rendererSchema),
   order: v.pipe(v.number(), v.integer(), v.minValue(0)),
-  id: caseIdSchema,
+  id: chartsCatalogCaseIdSchema,
   title: v.pipe(v.string(), v.nonEmpty()),
   family: v.pipe(v.string(), v.nonEmpty()),
   intent: v.pipe(v.string(), v.nonEmpty()),
@@ -496,8 +508,8 @@ export function getChartsCatalogSitemapEntries(
   manifest: ChartsCatalogManifest,
 ) {
   return [
-    { path: '/charts/catalog/' },
-    { path: '/charts/catalog/all/' },
+    { path: chartsCatalogBasePath },
+    { path: `${chartsCatalogBasePath}all/` },
     ...manifest.cases.map((catalogCase) => ({
       path: catalogCase.routes.page,
     })),
diff --git a/src/utils/documents.server.ts b/src/utils/documents.server.ts
index ca0108228..2218b56a6 100644
--- a/src/utils/documents.server.ts
+++ b/src/utils/documents.server.ts
@@ -15,6 +15,7 @@ import {
   InvalidCacheKeyError,
 } from './github-content-cache.server'
 import { normalizeRedirectFrom } from './redirects'
+import { isValidRepoPath } from './repo-path'
 import { multiSortBy, removeLeadingSlash } from './utils'
 import { env } from './env'
 import { fetchWithTimeout } from './outbound-fetch.server'
@@ -536,6 +537,12 @@ export async function fetchRepoRawFile(
   ref: string,
   filepath: string,
 ) {
+  assertValidGitHubRepoPair(repoPair)
+  assertValidGitHubRef(ref)
+  if (!filepath || !isValidRepoPath(filepath)) {
+    throw new InvalidCacheKeyError('path', filepath)
+  }
+
   const key = `raw:${repoPair}:${ref}:${filepath}`
 
   if (shouldUseLocalDocsFiles()) {
@@ -593,24 +600,8 @@ export async function fetchRepoFile(
 }
 
 export async function resolveGitHubRef(repoPair: string, gitRef: string) {
-  if (
-    repoPair.length === 0 ||
-    repoPair.length > 100 ||
-    !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repoPair)
-  ) {
-    throw new InvalidCacheKeyError('repo', repoPair)
-  }
-  if (
-    gitRef.length === 0 ||
-    gitRef.length > 100 ||
-    !/^[a-zA-Z0-9._/-]+$/.test(gitRef) ||
-    gitRef.includes('..') ||
-    gitRef.startsWith('/') ||
-    gitRef.endsWith('/') ||
-    gitRef.includes('//')
-  ) {
-    throw new InvalidCacheKeyError('gitRef', gitRef)
-  }
+  assertValidGitHubRepoPair(repoPair)
+  assertValidGitHubRef(gitRef)
 
   const encodedRef = gitRef
     .split('/')
@@ -688,6 +679,32 @@ export async function resolveGitHubRef(repoPair: string, gitRef: string) {
   return value.object.sha
 }
 
+function assertValidGitHubRepoPair(repoPair: string) {
+  const segments = repoPair.split('/')
+  if (
+    repoPair.length === 0 ||
+    repoPair.length > 100 ||
+    !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repoPair) ||
+    segments.some((segment) => segment === '.' || segment === '..')
+  ) {
+    throw new InvalidCacheKeyError('repo', repoPair)
+  }
+}
+
+function assertValidGitHubRef(gitRef: string) {
+  if (
+    gitRef.length === 0 ||
+    gitRef.length > 100 ||
+    !/^[a-zA-Z0-9._/-]+$/.test(gitRef) ||
+    gitRef.includes('..') ||
+    gitRef.startsWith('/') ||
+    gitRef.endsWith('/') ||
+    gitRef.includes('//')
+  ) {
+    throw new InvalidCacheKeyError('gitRef', gitRef)
+  }
+}
+
 export function extractFrontMatter(content: string) {
   const parsed = parseFrontMatter(content)
   const redirectFrom = normalizeRedirectFrom(parsed.data.redirect_from)
diff --git a/tests/charts-catalog-assets.test.ts b/tests/charts-catalog-assets.test.ts
index 0a8882037..2f082aa6d 100644
--- a/tests/charts-catalog-assets.test.ts
+++ b/tests/charts-catalog-assets.test.ts
@@ -8,6 +8,12 @@ import {
   getChartsCatalogAssetUrl,
   parseChartsCatalogManifest,
 } from '../src/utils/charts-catalog'
+import {
+  ChartsCatalogIntegrityError,
+  ChartsCatalogResourceNotFoundError,
+  classifyChartsCatalogAssetError,
+} from '../src/utils/charts-catalog.server'
+import { GitHubContentError } from '../src/utils/documents.server'
 import {
   artifactRevision,
   createChartsCatalogManifest,
@@ -88,3 +94,32 @@ test('catalog JavaScript uses immutable same-origin response headers', () => {
   assert.equal(headers.get('X-Content-Type-Options'), 'nosniff')
   assert.equal(headers.get('Access-Control-Allow-Origin'), null)
 })
+
+test('catalog asset failures preserve missing, transient, and integrity semantics', () => {
+  assert.equal(
+    classifyChartsCatalogAssetError(
+      new ChartsCatalogResourceNotFoundError('missing'),
+    ),
+    'not-found',
+  )
+
+  for (const kind of ['network', 'rate-limit', 'server'] as const) {
+    assert.equal(
+      classifyChartsCatalogAssetError(new GitHubContentError(kind, kind)),
+      'unavailable',
+    )
+  }
+
+  assert.equal(
+    classifyChartsCatalogAssetError(
+      new ChartsCatalogIntegrityError('digest mismatch'),
+    ),
+    'internal',
+  )
+  assert.equal(
+    classifyChartsCatalogAssetError(
+      new GitHubContentError('invalid-response', 'invalid response'),
+    ),
+    'internal',
+  )
+})
diff --git a/tests/charts-catalog-manifest.test.ts b/tests/charts-catalog-manifest.test.ts
index 802543d40..781ec9031 100644
--- a/tests/charts-catalog-manifest.test.ts
+++ b/tests/charts-catalog-manifest.test.ts
@@ -59,6 +59,10 @@ expectRejected('a different site origin', (manifest) => {
   manifest.site.origin = 'https://example.com'
 })
 
+expectRejected('a non-HTTPS source URL', (manifest) => {
+  manifest.cases[0].source.url = 'http://observablehq.com/plot/marks/line'
+})
+
 expectRejected('an altered embed protocol', (manifest) => {
   manifest.embed.protocol.version = 2
 })
diff --git a/tests/charts-catalog-raw-content.test.ts b/tests/charts-catalog-raw-content.test.ts
index aa4ddacc8..544b6a18c 100644
--- a/tests/charts-catalog-raw-content.test.ts
+++ b/tests/charts-catalog-raw-content.test.ts
@@ -1,7 +1,10 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 import { fetchRepoFile, fetchRepoRawFile } from '../src/utils/documents.server'
-import { resetGitHubContentCacheForTest } from '../src/utils/github-content-cache.server'
+import {
+  InvalidCacheKeyError,
+  resetGitHubContentCacheForTest,
+} from '../src/utils/github-content-cache.server'
 
 test('raw GitHub content remains byte-for-byte text-equivalent', async () => {
   resetGitHubContentCacheForTest()
@@ -39,3 +42,37 @@ test('raw GitHub content remains byte-for-byte text-equivalent', async () => {
     globalThis.fetch = originalFetch
   }
 })
+
+test('raw GitHub content rejects unsafe inputs before fetching', async () => {
+  const originalFetch = globalThis.fetch
+  let originCalls = 0
+
+  globalThis.fetch = async () => {
+    originCalls += 1
+    return new Response('unexpected')
+  }
+
+  try {
+    const invalidInputs = [
+      ['tanstack/charts/extra', 'main', 'catalog.json'],
+      ['tanstack/..', 'main', 'catalog.json'],
+      ['tanstack/charts', '../main', 'catalog.json'],
+      ['tanstack/charts', 'main', ''],
+      ['tanstack/charts', 'main', '../catalog.json'],
+      ['tanstack/charts', 'main', '/catalog.json'],
+      ['tanstack/charts', 'main', 'assets//catalog.js'],
+      ['tanstack/charts', 'main', 'assets\\catalog.js'],
+    ] as const
+
+    for (const [repo, ref, path] of invalidInputs) {
+      await assert.rejects(
+        fetchRepoRawFile(repo, ref, path),
+        InvalidCacheKeyError,
+      )
+    }
+
+    assert.equal(originCalls, 0)
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
diff --git a/tests/charts-catalog-site-contracts.test.ts b/tests/charts-catalog-site-contracts.test.ts
index 9ea4de85e..5e08acae8 100644
--- a/tests/charts-catalog-site-contracts.test.ts
+++ b/tests/charts-catalog-site-contracts.test.ts
@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 import {
+  chartsCatalogPublicationCacheHeaders,
   chartsCatalogPublicationCacheTag,
   getChartsCatalogSitemapEntries,
   parseChartsCatalogManifest,
@@ -56,3 +57,12 @@ test('catalog publication pushes invalidate the GitHub content pipeline', () =>
   assert.ok(chartsSource)
   assert.ok(chartsSource.refs.includes('catalog-dist'))
 })
+
+test('catalog publication responses share one cache contract', () => {
+  assert.deepEqual(chartsCatalogPublicationCacheHeaders, {
+    'Cache-Control': 'public, max-age=60, must-revalidate',
+    'Cloudflare-CDN-Cache-Control':
+      'public, max-age=300, stale-while-revalidate=300',
+    'Cache-Tag': chartsCatalogPublicationCacheTag,
+  })
+})

From bdc6ea25cfa73159d763750546c4da49fdcf246d Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 23:40:30 -0600
Subject: [PATCH 6/9] Keep catalog comparison gating exact

---
 src/utils/charts-catalog.ts         |  4 ++--
 tests/charts-catalog-search.test.ts | 15 ++++++++++++++-
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/utils/charts-catalog.ts b/src/utils/charts-catalog.ts
index beb404b58..34249d14f 100644
--- a/src/utils/charts-catalog.ts
+++ b/src/utils/charts-catalog.ts
@@ -470,9 +470,9 @@ export function parseChartsCatalogRouteSearch(
   options: { embed?: boolean } = {},
 ) {
   const comparisonValues =
-    !Array.isArray(search.compare) && search.compare !== undefined
+    search.compare !== undefined && !Array.isArray(search.compare)
       ? [search.compare]
-      : (search.compare ?? [])
+      : []
 
   return {
     comparison: isChartsCatalogComparisonEnabled(comparisonValues, options),
diff --git a/tests/charts-catalog-search.test.ts b/tests/charts-catalog-search.test.ts
index e59499a23..d8cf1fc6e 100644
--- a/tests/charts-catalog-search.test.ts
+++ b/tests/charts-catalog-search.test.ts
@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
+import { defaultParseSearch } from '@tanstack/react-router'
 import {
   parseChartsCatalogRouteSearch,
   parseChartsCatalogSearch,
@@ -31,6 +32,8 @@ test('catalog comparison mode requires one exact compare=1 parameter', () => {
     '?compare=1&compare=1',
     '?compare=0&compare=1',
     '?compare=1&compare=0',
+    '?compare=%5B1%5D',
+    '?compare=%5B%221%22%5D',
   ]) {
     assert.equal(
       parseChartsCatalogSearch(search).comparison,
@@ -48,7 +51,7 @@ test('catalog embeds never enable comparison modules', () => {
 })
 
 test('validated catalog search preserves exact comparison loader deps', () => {
-  for (const value of ['1', 1, ['1'], [1]]) {
+  for (const value of ['1', 1]) {
     const search = validateChartsCatalogRouteSearch({ compare: value })
     assert.equal(parseChartsCatalogRouteSearch(search).comparison, true)
   }
@@ -60,6 +63,8 @@ test('validated catalog search preserves exact comparison loader deps', () => {
     'true',
     true,
     1.1,
+    ['1'],
+    [1],
     ['1', '1'],
     [1, 1],
     ['0', '1'],
@@ -69,6 +74,14 @@ test('validated catalog search preserves exact comparison loader deps', () => {
   }
 })
 
+test('Router-decoded array values never enable catalog comparison mode', () => {
+  for (const value of ['%5B1%5D', '%5B%221%22%5D']) {
+    const decoded = defaultParseSearch(`?compare=${value}`)
+    const search = validateChartsCatalogRouteSearch(decoded)
+    assert.equal(parseChartsCatalogRouteSearch(search).comparison, false)
+  }
+})
+
 test('validated embed search produces stable loader deps', () => {
   assert.deepEqual(
     parseChartsCatalogEmbedRouteSearch(

From 7c0e4186a03dc0d5e7158aaac0f6547448ad78aa Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 23:46:34 -0600
Subject: [PATCH 7/9] Gate catalog assets to published revisions

---
 src/utils/charts-catalog.server.ts  | 68 +++++++++++++++++++++++------
 src/utils/documents.server.ts       | 54 +++++++++++++++++++++++
 tests/charts-catalog-assets.test.ts | 67 ++++++++++++++++++++++++++++
 3 files changed, 176 insertions(+), 13 deletions(-)

diff --git a/src/utils/charts-catalog.server.ts b/src/utils/charts-catalog.server.ts
index 3a0af5a47..16004a7ab 100644
--- a/src/utils/charts-catalog.server.ts
+++ b/src/utils/charts-catalog.server.ts
@@ -1,10 +1,10 @@
 import {
+  fetchGitHubCommitHistory,
   fetchRepoRawFile,
   GitHubContentError,
-  resolveGitHubRef,
   shouldUseLocalDocsFiles,
 } from './documents.server'
-import { getCachedGitHubTextFile } from './github-content-cache.server'
+import { getCachedGitHubJsonContent } from './github-content-cache.server'
 import {
   chartsCatalogPublicationRef,
   chartsCatalogRepo,
@@ -14,7 +14,9 @@ import {
 
 const catalogManifestPath = 'catalog.json'
 const localCatalogRoot = '.catalog-artifact'
-const catalogHeadCachePath = '.tanstack/catalog-dist-head'
+const catalogRevisionHistoryCachePath =
+  '.tanstack/catalog-dist-revision-history'
+const catalogRevisionHistoryLimit = 100
 const exactGitShaPattern = /^[a-f0-9]{40}$/
 
 export class ChartsCatalogResourceNotFoundError extends Error {
@@ -55,7 +57,8 @@ export async function getChartsCatalogPublication(): Promise<ChartsCatalogPublic
     }
   }
 
-  const artifactRevision = await resolveChartsCatalogArtifactRevision()
+  const revisions = await getPublishedChartsCatalogRevisions()
+  const artifactRevision = revisions[0]
   return {
     artifactRevision,
     manifest: await readChartsCatalogManifest(artifactRevision),
@@ -70,6 +73,26 @@ export async function getChartsCatalogManifestAtRevision(
       'Invalid Charts catalog artifact revision',
     )
   }
+
+  if (shouldUseLocalDocsFiles()) {
+    const manifest = await readChartsCatalogManifest(
+      chartsCatalogPublicationRef,
+    )
+    if (artifactRevision !== manifest.revision) {
+      throw new ChartsCatalogResourceNotFoundError(
+        'Unpublished Charts catalog artifact revision',
+      )
+    }
+    return manifest
+  }
+
+  const publishedRevisions = await getPublishedChartsCatalogRevisions()
+  if (!publishedRevisions.includes(artifactRevision)) {
+    throw new ChartsCatalogResourceNotFoundError(
+      'Unpublished Charts catalog artifact revision',
+    )
+  }
+
   return readChartsCatalogManifest(artifactRevision)
 }
 
@@ -160,20 +183,39 @@ async function readChartsCatalogManifest(artifactRevision: string) {
   }
 }
 
-async function resolveChartsCatalogArtifactRevision() {
-  const revision = await getCachedGitHubTextFile({
+async function getPublishedChartsCatalogRevisions() {
+  const revisions = await getCachedGitHubJsonContent({
     repo: chartsCatalogRepo,
     gitRef: chartsCatalogPublicationRef,
-    path: catalogHeadCachePath,
-    origin: fetchChartsCatalogArtifactRevision,
+    path: catalogRevisionHistoryCachePath,
+    isValue: isChartsCatalogRevisionHistory,
+    origin: () =>
+      fetchGitHubCommitHistory(
+        chartsCatalogRepo,
+        chartsCatalogPublicationRef,
+        catalogRevisionHistoryLimit,
+      ),
   })
 
-  if (!revision || !exactGitShaPattern.test(revision)) {
-    throw new Error('Charts catalog publication revision is unavailable')
+  if (!revisions) {
+    throw new ChartsCatalogIntegrityError(
+      'Charts catalog publication history is unavailable',
+    )
   }
-  return revision
+  return revisions
 }
 
-async function fetchChartsCatalogArtifactRevision() {
-  return resolveGitHubRef(chartsCatalogRepo, chartsCatalogPublicationRef)
+function isChartsCatalogRevisionHistory(
+  value: unknown,
+): value is Array<string> {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= catalogRevisionHistoryLimit &&
+    value.every(
+      (revision) =>
+        typeof revision === 'string' && exactGitShaPattern.test(revision),
+    ) &&
+    new Set(value).size === value.length
+  )
 }
diff --git a/src/utils/documents.server.ts b/src/utils/documents.server.ts
index 2218b56a6..30c6b45be 100644
--- a/src/utils/documents.server.ts
+++ b/src/utils/documents.server.ts
@@ -679,6 +679,60 @@ export async function resolveGitHubRef(repoPair: string, gitRef: string) {
   return value.object.sha
 }
 
+export async function fetchGitHubCommitHistory(
+  repoPair: string,
+  gitRef: string,
+  limit: number,
+) {
+  assertValidGitHubRepoPair(repoPair)
+  assertValidGitHubRef(gitRef)
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new InvalidCacheKeyError('commitHistoryLimit', String(limit))
+  }
+
+  const url = new URL(`https://api.github.com/repos/${repoPair}/commits`)
+  url.searchParams.set('sha', gitRef)
+  url.searchParams.set('per_page', String(limit))
+
+  const response = await fetchGitHubApiJson(url.href)
+  if (
+    !Array.isArray(response) ||
+    response.length === 0 ||
+    response.length > limit
+  ) {
+    throw new GitHubContentError(
+      'invalid-response',
+      `Unexpected commit history response for ${repoPair}@${gitRef}`,
+    )
+  }
+
+  const revisions = new Array<string>()
+  for (const commit of response) {
+    if (
+      typeof commit !== 'object' ||
+      commit === null ||
+      !('sha' in commit) ||
+      typeof commit.sha !== 'string' ||
+      !/^[a-f0-9]{40}$/.test(commit.sha)
+    ) {
+      throw new GitHubContentError(
+        'invalid-response',
+        `Unexpected commit history response for ${repoPair}@${gitRef}`,
+      )
+    }
+    revisions.push(commit.sha)
+  }
+
+  if (new Set(revisions).size !== revisions.length) {
+    throw new GitHubContentError(
+      'invalid-response',
+      `Duplicate commit in history for ${repoPair}@${gitRef}`,
+    )
+  }
+
+  return revisions
+}
+
 function assertValidGitHubRepoPair(repoPair: string) {
   const segments = repoPair.split('/')
   if (
diff --git a/tests/charts-catalog-assets.test.ts b/tests/charts-catalog-assets.test.ts
index 2f082aa6d..bece7d7b1 100644
--- a/tests/charts-catalog-assets.test.ts
+++ b/tests/charts-catalog-assets.test.ts
@@ -12,8 +12,13 @@ import {
   ChartsCatalogIntegrityError,
   ChartsCatalogResourceNotFoundError,
   classifyChartsCatalogAssetError,
+  getChartsCatalogManifestAtRevision,
 } from '../src/utils/charts-catalog.server'
 import { GitHubContentError } from '../src/utils/documents.server'
+import {
+  listDocsCacheRepoStats,
+  resetGitHubContentCacheForTest,
+} from '../src/utils/github-content-cache.server'
 import {
   artifactRevision,
   createChartsCatalogManifest,
@@ -123,3 +128,65 @@ test('catalog asset failures preserve missing, transient, and integrity semantic
     'internal',
   )
 })
+
+test('catalog assets admit recent published revisions without caching random SHAs', async () => {
+  resetGitHubContentCacheForTest()
+
+  const originalFetch = globalThis.fetch
+  const historicalRevision = '3'.repeat(40)
+  const unpublishedRevisions = ['4'.repeat(40), '5'.repeat(40)]
+  const requests = new Array<string>()
+
+  globalThis.fetch = async (input) => {
+    const url = String(input)
+    requests.push(url)
+
+    if (
+      url.startsWith('https://api.github.com/repos/tanstack/charts/commits?')
+    ) {
+      return Response.json([
+        { sha: artifactRevision },
+        { sha: historicalRevision },
+      ])
+    }
+
+    if (
+      url ===
+      `https://raw.githubusercontent.com/tanstack/charts/${historicalRevision}/catalog.json`
+    ) {
+      return Response.json(createChartsCatalogManifest())
+    }
+
+    return new Response('Not found', { status: 404 })
+  }
+
+  try {
+    for (const unpublishedRevision of unpublishedRevisions) {
+      await assert.rejects(
+        getChartsCatalogManifestAtRevision(unpublishedRevision),
+        ChartsCatalogResourceNotFoundError,
+      )
+    }
+    assert.equal(requests.length, 1)
+
+    const statsAfterRejection = await listDocsCacheRepoStats()
+    assert.equal(statsAfterRejection[0]?.contentEntries, 1)
+    assert.equal(statsAfterRejection[0]?.cachedRefCount, 1)
+
+    const historicalManifest =
+      await getChartsCatalogManifestAtRevision(historicalRevision)
+    assert.equal(historicalManifest.revision, '1'.repeat(40))
+    assert.equal(requests.length, 2)
+    assert.equal(
+      requests[1],
+      `https://raw.githubusercontent.com/tanstack/charts/${historicalRevision}/catalog.json`,
+    )
+
+    const statsAfterHistoricalRead = await listDocsCacheRepoStats()
+    assert.equal(statsAfterHistoricalRead[0]?.contentEntries, 2)
+    assert.equal(statsAfterHistoricalRead[0]?.cachedRefCount, 2)
+  } finally {
+    globalThis.fetch = originalFetch
+    resetGitHubContentCacheForTest()
+  }
+})

From 6192b44f610fc89f139cd7ce4b7c6dd9102e22ba Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Tue, 28 Jul 2026 23:56:45 -0600
Subject: [PATCH 8/9] Return HTTP 404 for missing catalog assets

---
 ...rts.catalog_.assets.$artifactRevision.$.ts |  39 ++-
 tests/charts-catalog-asset-route.test.ts      | 230 ++++++++++++++++++
 2 files changed, 262 insertions(+), 7 deletions(-)
 create mode 100644 tests/charts-catalog-asset-route.test.ts

diff --git a/src/routes/charts.catalog_.assets.$artifactRevision.$.ts b/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
index 114d9b7ca..0b495ee71 100644
--- a/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
+++ b/src/routes/charts.catalog_.assets.$artifactRevision.$.ts
@@ -1,6 +1,14 @@
-import { createFileRoute, notFound } from '@tanstack/react-router'
+import { createFileRoute } from '@tanstack/react-router'
 import { parseChartsCatalogAssetRequest } from '~/utils/charts-catalog-assets'
 
+const catalogAssetNotFoundBody = 'Charts catalog asset not found'
+const catalogAssetNoStoreHeaders = {
+  'Cache-Control': 'no-store',
+  'Cloudflare-CDN-Cache-Control': 'no-store',
+  'Content-Type': 'text/plain; charset=utf-8',
+  'X-Content-Type-Options': 'nosniff',
+}
+
 export const Route = createFileRoute(
   '/charts/catalog_/assets/$artifactRevision/$',
 )({
@@ -12,7 +20,7 @@ export const Route = createFileRoute(
   },
 })
 
-async function serveCatalogAsset({
+export async function serveCatalogAsset({
   request,
   params,
 }: {
@@ -44,12 +52,16 @@ async function serveCatalogAsset({
       manifest,
     })
   } catch (error) {
-    if (error instanceof TypeError) throw notFound()
+    if (error instanceof TypeError) {
+      return createCatalogAssetNotFoundResponse(request.method)
+    }
     throw error
   }
 
   const descriptor = manifest.assets[asset.repoPath]
-  if (!descriptor) throw notFound()
+  if (!descriptor) {
+    return createCatalogAssetNotFoundResponse(request.method)
+  }
 
   let source: string
   try {
@@ -80,7 +92,9 @@ function handleCatalogAssetError(
   method: string,
 ) {
   const classification = classify(error)
-  if (classification === 'not-found') throw notFound()
+  if (classification === 'not-found') {
+    return createCatalogAssetNotFoundResponse(method)
+  }
 
   console.error('[Charts catalog asset] Failed to serve asset', error)
   if (classification === 'unavailable') {
@@ -89,8 +103,7 @@ function handleCatalogAssetError(
       {
         status: 503,
         headers: {
-          'Cache-Control': 'no-store',
-          'Cloudflare-CDN-Cache-Control': 'no-store',
+          ...catalogAssetNoStoreHeaders,
           'Retry-After': '60',
         },
       },
@@ -99,3 +112,15 @@ function handleCatalogAssetError(
 
   throw error
 }
+
+function createCatalogAssetNotFoundResponse(method: string) {
+  return new Response(method === 'HEAD' ? null : catalogAssetNotFoundBody, {
+    status: 404,
+    headers: {
+      ...catalogAssetNoStoreHeaders,
+      'Content-Length': String(
+        new TextEncoder().encode(catalogAssetNotFoundBody).byteLength,
+      ),
+    },
+  })
+}
diff --git a/tests/charts-catalog-asset-route.test.ts b/tests/charts-catalog-asset-route.test.ts
new file mode 100644
index 000000000..63584e658
--- /dev/null
+++ b/tests/charts-catalog-asset-route.test.ts
@@ -0,0 +1,230 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { serveCatalogAsset } from '../src/routes/charts.catalog_.assets.$artifactRevision.$'
+import { ChartsCatalogIntegrityError } from '../src/utils/charts-catalog.server'
+import { resetGitHubContentCacheForTest } from '../src/utils/github-content-cache.server'
+import {
+  artifactRevision,
+  createChartsCatalogManifest,
+  tanstackAsset,
+} from './charts-catalog-test-fixture'
+
+const notFoundBody = 'Charts catalog asset not found'
+
+test('catalog asset handler returns explicit no-store 404 responses', async () => {
+  resetGitHubContentCacheForTest()
+
+  const originalFetch = globalThis.fetch
+  const unpublishedRevision = '4'.repeat(40)
+  const requests = new Array<string>()
+
+  globalThis.fetch = async (input) => {
+    const url = String(input)
+    requests.push(url)
+
+    if (
+      url.startsWith('https://api.github.com/repos/tanstack/charts/commits?')
+    ) {
+      return Response.json([{ sha: artifactRevision }])
+    }
+
+    if (
+      url ===
+      `https://raw.githubusercontent.com/tanstack/charts/${artifactRevision}/catalog.json`
+    ) {
+      return Response.json(createChartsCatalogManifest())
+    }
+
+    return new Response('Not found', { status: 404 })
+  }
+
+  try {
+    const invalidRevision = await requestCatalogAsset({
+      artifactRevision: 'main',
+      assetPath: tanstackAsset,
+      method: 'GET',
+    })
+    await assertNotFoundResponse(invalidRevision, 'GET')
+
+    const unpublished = await requestCatalogAsset({
+      artifactRevision: unpublishedRevision,
+      assetPath: tanstackAsset,
+      method: 'GET',
+    })
+    await assertNotFoundResponse(unpublished, 'GET')
+
+    const unlisted = await requestCatalogAsset({
+      artifactRevision,
+      assetPath: 'assets/tanstack-invalid.js',
+      method: 'GET',
+    })
+    await assertNotFoundResponse(unlisted, 'GET')
+
+    const unlistedHead = await requestCatalogAsset({
+      artifactRevision,
+      assetPath: 'assets/tanstack-invalid.js',
+      method: 'HEAD',
+    })
+    await assertNotFoundResponse(unlistedHead, 'HEAD')
+
+    assert.deepEqual(requests, [
+      'https://api.github.com/repos/tanstack/charts/commits?sha=catalog-dist&per_page=100',
+      `https://raw.githubusercontent.com/tanstack/charts/${artifactRevision}/catalog.json`,
+    ])
+    assert.equal(
+      requests.some((url) => url.includes(unpublishedRevision)),
+      false,
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+    resetGitHubContentCacheForTest()
+  }
+})
+
+test('catalog asset handler returns 404 for missing manifests and files', async () => {
+  const originalFetch = globalThis.fetch
+
+  try {
+    resetGitHubContentCacheForTest()
+    globalThis.fetch = async (input) => {
+      const url = String(input)
+      if (
+        url.startsWith('https://api.github.com/repos/tanstack/charts/commits?')
+      ) {
+        return Response.json([{ sha: artifactRevision }])
+      }
+      return new Response('Not found', { status: 404 })
+    }
+
+    const missingManifest = await requestCatalogAsset({
+      artifactRevision,
+      assetPath: tanstackAsset,
+      method: 'GET',
+    })
+    await assertNotFoundResponse(missingManifest, 'GET')
+
+    resetGitHubContentCacheForTest()
+    globalThis.fetch = async (input) => {
+      const url = String(input)
+      if (
+        url.startsWith('https://api.github.com/repos/tanstack/charts/commits?')
+      ) {
+        return Response.json([{ sha: artifactRevision }])
+      }
+      if (
+        url ===
+        `https://raw.githubusercontent.com/tanstack/charts/${artifactRevision}/catalog.json`
+      ) {
+        return Response.json(createChartsCatalogManifest())
+      }
+      return new Response('Not found', { status: 404 })
+    }
+
+    const missingAsset = await requestCatalogAsset({
+      artifactRevision,
+      assetPath: tanstackAsset,
+      method: 'GET',
+    })
+    await assertNotFoundResponse(missingAsset, 'GET')
+  } finally {
+    globalThis.fetch = originalFetch
+    resetGitHubContentCacheForTest()
+  }
+})
+
+test('catalog asset handler preserves transient and integrity failures', async () => {
+  const originalFetch = globalThis.fetch
+  const originalConsoleError = console.error
+
+  try {
+    console.error = () => undefined
+    resetGitHubContentCacheForTest()
+    globalThis.fetch = async () => new Response('Unavailable', { status: 500 })
+
+    const unavailable = await requestCatalogAsset({
+      artifactRevision,
+      assetPath: tanstackAsset,
+      method: 'GET',
+    })
+    assert.equal(unavailable.status, 503)
+    assert.equal(unavailable.headers.get('Cache-Control'), 'no-store')
+    assert.equal(
+      unavailable.headers.get('Cloudflare-CDN-Cache-Control'),
+      'no-store',
+    )
+    assert.equal(unavailable.headers.get('Retry-After'), '60')
+    assert.equal(
+      await unavailable.text(),
+      'Charts catalog asset temporarily unavailable',
+    )
+
+    resetGitHubContentCacheForTest()
+    globalThis.fetch = async (input) => {
+      const url = String(input)
+      if (
+        url.startsWith('https://api.github.com/repos/tanstack/charts/commits?')
+      ) {
+        return Response.json([{ sha: artifactRevision }])
+      }
+      if (
+        url ===
+        `https://raw.githubusercontent.com/tanstack/charts/${artifactRevision}/catalog.json`
+      ) {
+        return Response.json(createChartsCatalogManifest())
+      }
+      return new Response('tampered asset')
+    }
+
+    await assert.rejects(
+      requestCatalogAsset({
+        artifactRevision,
+        assetPath: tanstackAsset,
+        method: 'GET',
+      }),
+      ChartsCatalogIntegrityError,
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+    console.error = originalConsoleError
+    resetGitHubContentCacheForTest()
+  }
+})
+
+function requestCatalogAsset({
+  artifactRevision,
+  assetPath,
+  method,
+}: {
+  artifactRevision: string
+  assetPath: string
+  method: 'GET' | 'HEAD'
+}) {
+  return serveCatalogAsset({
+    request: new Request(
+      `https://tanstack.com/charts/catalog/assets/${artifactRevision}/${assetPath}`,
+      { method },
+    ),
+    params: {
+      artifactRevision,
+      _splat: assetPath,
+    },
+  })
+}
+
+async function assertNotFoundResponse(
+  response: Response,
+  method: 'GET' | 'HEAD',
+) {
+  assert.equal(response.status, 404)
+  assert.equal(response.headers.get('Cache-Control'), 'no-store')
+  assert.equal(response.headers.get('Cloudflare-CDN-Cache-Control'), 'no-store')
+  assert.equal(
+    response.headers.get('Content-Type'),
+    'text/plain; charset=utf-8',
+  )
+  assert.equal(
+    response.headers.get('Content-Length'),
+    String(new TextEncoder().encode(notFoundBody).byteLength),
+  )
+  assert.equal(await response.text(), method === 'HEAD' ? '' : notFoundBody)
+}

From c82d3914024a78f398336aed2e010e0fbed6c19c Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Wed, 29 Jul 2026 00:15:03 -0600
Subject: [PATCH 9/9] Commit chart runtime ref updates

---
 src/components/charts/ChartsCatalogChart.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/components/charts/ChartsCatalogChart.tsx b/src/components/charts/ChartsCatalogChart.tsx
index bbfca1e2a..94d5230c6 100644
--- a/src/components/charts/ChartsCatalogChart.tsx
+++ b/src/components/charts/ChartsCatalogChart.tsx
@@ -48,8 +48,13 @@ export function ChartsCatalogChart({
   const [visible, setVisible] = React.useState(!defer)
   const [failed, setFailed] = React.useState(false)
 
-  inputRef.current = { height, interactive, revision }
-  onStatusRef.current = onStatus
+  React.useEffect(() => {
+    inputRef.current = { height, interactive, revision }
+  }, [height, interactive, revision])
+
+  React.useEffect(() => {
+    onStatusRef.current = onStatus
+  }, [onStatus])
 
   React.useEffect(() => {
     const container = containerRef.current