@seed-ship/mcp-ui-solid 6.22.0 → 6.24.0

package/src/services/validation.ts

@@ -45,6 +45,8 @@ import type {
 // Runtime-free template helper: `src/validation.ts` (the SSR-safe subpath)
 // re-exports this module, so it must stay free of any solid-js import.
 import { formatMCPUIString } from '../utils/format-string';
+// Runtime-free as well (v6.24.0): the missing-value rules shared with the renderers.
+import { PART_TO_WHOLE_CHART_TYPES } from '../utils/missing-value';
 
 /**
  * All known ComponentType values — used to distinguish known-but-unvalidated
@@ -477,38 +479,71 @@ export function validateChartComponent(
     }
   }
 
-  // Data type validation — numbers for categorical, {x,y} objects for point charts
+  // Data type validation — numbers for categorical, {x,y} objects for point charts.
+  //
+  // `null` is an explicit missing value (v6.24.0): a number slot, or a point's
+  // `y`, that exists but was not observed. Line, bar, radar, scatter and bubble
+  // charts keep its slot and mark it. Pie, doughnut and polar-area charts
+  // cannot: Chart.js parses a null share as `0`, so the other shares and the
+  // wedge itself would all be drawn wrong — those types refuse it.
+  const missingUnsupported = PART_TO_WHOLE_CHART_TYPES.has(chartType);
   for (const [index, dataset] of params.data.datasets.entries()) {
     if (!Array.isArray(dataset.data)) continue;
     const datasetIsPointChart = chartType === 'scatter' || chartType === 'bubble' || usesPoints(dataset.data);
     for (const [dataIndex, value] of dataset.data.entries()) {
+      const path = `params.data.datasets[${index}].data[${dataIndex}]`;
       if (datasetIsPointChart) {
         const vObj = value as any;
         if (
           typeof value !== 'object' ||
           value === null ||
           vObj.x == null ||
-          typeof vObj.y !== 'number' ||
+          (vObj.y !== null && typeof vObj.y !== 'number') ||
           (vObj.r !== undefined && (typeof vObj.r !== 'number' || !Number.isFinite(vObj.r) || vObj.r < 0))
         ) {
           errors.push({
-            path: `params.data.datasets[${index}].data[${dataIndex}]`,
-            message: `Invalid point data: expected {x, y} object`,
+            path,
+            message: `Invalid point data: expected {x, y} object (y may be null for a missing value)`,
             code: 'INVALID_POINT_DATA',
           });
+        } else if (missingUnsupported && vObj.y === null) {
+          errors.push({
+            path,
+            message: `Missing value (null) is not supported by '${chartType}' charts, which would draw it as a zero share — use a bar or line chart, or a table`,
+            code: 'MISSING_VALUE_UNSUPPORTED',
+          });
         }
-      } else {
-        if (typeof value !== 'number' || !Number.isFinite(value)) {
+      } else if (value === null) {
+        if (missingUnsupported) {
           errors.push({
-            path: `params.data.datasets[${index}].data[${dataIndex}]`,
-            message: `Invalid data value: ${value} (must be finite number)`,
-            code: 'INVALID_DATA_TYPE',
+            path,
+            message: `Missing value (null) is not supported by '${chartType}' charts, which would draw it as a zero share — use a bar or line chart, or a table`,
+            code: 'MISSING_VALUE_UNSUPPORTED',
           });
         }
+      } else if (typeof value !== 'number' || !Number.isFinite(value)) {
+        errors.push({
+          path,
+          message: `Invalid data value: ${value} (must be a finite number, or null for a missing value)`,
+          code: 'INVALID_DATA_TYPE',
+        });
       }
     }
   }
 
+  // `unit` (v6.24.0) ends up in the value-axis title, in every tooltip and in
+  // the data-view headers: a short string, or nothing. An empty string is
+  // tolerated — the renderer treats it as "no unit" — so a producer that
+  // emits `unit: ''` does not lose its whole chart over it.
+  const unit = (params as { unit?: unknown }).unit;
+  if (unit !== undefined && (typeof unit !== 'string' || unit.length > 32)) {
+    errors.push({
+      path: 'params.unit',
+      message: 'Invalid unit: expected a string of at most 32 characters',
+      code: 'INVALID_UNIT',
+    });
+  }
+
   return {
     valid: errors.length === 0,
     errors: errors.length > 0 ? errors : undefined,

package/src/types/index.ts

@@ -81,7 +81,13 @@ export interface ChartComponentParams {
     labels: string[]
     datasets: Array<{
       label: string
-      data: number[] | Array<{ x: string | number; y: number; r?: number }>
+      /**
+       * `null` is an explicit missing value (v6.24.0): its label keeps its
+       * slot, a line breaks there, a bar shows a dashed outline — never a
+       * zero. Pie, doughnut and polar-area charts reject it, since they
+       * would draw it as a zero share.
+       */
+      data: Array<number | null> | Array<{ x: string | number; y: number | null; r?: number }>
       backgroundColor?: string | string[]
       borderColor?: string | string[]
       borderWidth?: number
@@ -135,6 +141,12 @@ export interface ChartComponentParams {
    * Custom CSS class (Sprint 7)
    */
   className?: string
+  /**
+   * Unit of every value in the chart (`'mm'`, `'km/h'`), shown as the value
+   * axis title (unless `options.scales` already sets one), after each tooltip
+   * value, and in the data-view column headers (v6.24.0). One unit per chart.
+   */
+  unit?: string
 }
 
 /**

package/src/utils/degraded-projections.ts

@@ -12,6 +12,7 @@
  */
 
 import { formatMCPUIString } from './format-string';
+import { isMissingChartValue } from './missing-value';
 
 /**
  * Column headers and series names of the degraded tables.
@@ -46,10 +47,17 @@ export interface DegradedProjectionLabels {
   feature: string;
   /** Chart table — fallback dataset name. Template — `{n}`. */
   series: string;
+  /**
+   * Chart table — a dataset column header followed by the chart's `unit`.
+   * Template — `{label}`, `{unit}`. Only applied when the chart has a unit.
+   * Optional so that a complete labels table written for 6.20.0–6.23.0 still
+   * type-checks. @since v6.24.0
+   */
+  withUnit?: string;
 }
 
 /** English defaults for {@link DegradedProjectionLabels}. */
-export const DEGRADED_PROJECTION_LABELS: DegradedProjectionLabels = {
+export const DEGRADED_PROJECTION_LABELS: Required<DegradedProjectionLabels> = {
   source: 'Source',
   target: 'Target',
   label: 'Label',
@@ -61,6 +69,7 @@ export const DEGRADED_PROJECTION_LABELS: DegradedProjectionLabels = {
   marker: 'marker',
   feature: 'feature',
   series: 'Series {n}',
+  withUnit: '{label} ({unit})',
 };
 
 const withLabels = (labels?: Partial<DegradedProjectionLabels>): DegradedProjectionLabels => ({
@@ -73,6 +82,12 @@ export interface DegradedTable {
   rows: Array<Array<string | number>>;
 }
 
+/** A degraded chart table: its cells, plus which of them are missing values. */
+export interface DegradedChartTable extends DegradedTable {
+  /** Same shape as `rows`; `true` for a dataset entry that is missing. @since v6.24.0 */
+  missing: boolean[][];
+}
+
 const MAX_PROJECTED_ROWS = 200;
 
 /** Compact a value to a single table cell string. */
@@ -188,25 +203,50 @@ export function mapToDegradedTable(params: {
  * Chart → a series table: one row per label, one column per dataset. So a
  * chart that can't draw still shows its numbers. Point/object data (scatter,
  * bubble, time series) is stringified per cell.
+ *
+ * `missing` flags the cells whose dataset entry is a missing value (`null`
+ * or non-finite) so the table can mark them instead of showing an empty
+ * cell. A slot past the end of a shorter or empty dataset has no entry and is
+ * not flagged; a point object keeps its JSON text (where a `"y":null` reads
+ * as such) and is not flagged either. With a `unit`, dataset column headers
+ * become `labels.withUnit`.
  */
 export function chartToDegradedTable(params: {
+  unit?: string;
   data?: {
     labels?: Array<string | number>;
     datasets?: Array<{ label?: string; data?: unknown[] }>;
   };
-}, labels?: Partial<DegradedProjectionLabels>): DegradedTable {
+}, labels?: Partial<DegradedProjectionLabels>): DegradedChartTable {
   const l = withLabels(labels);
+  const unit = typeof params.unit === 'string' && params.unit !== '' ? params.unit : undefined;
   const datasets = params.data?.datasets ?? [];
   const dataLabels = params.data?.labels ?? [];
   const rowCount = Math.max(dataLabels.length, ...datasets.map((d) => d.data?.length ?? 0), 0);
 
   const columns = [
     '',
-    ...datasets.map((d, i) => d.label ?? formatMCPUIString(l.series, { n: i + 1 })),
+    ...datasets.map((d, i) => {
+      const name = d.label ?? formatMCPUIString(l.series, { n: i + 1 });
+      return unit === undefined
+        ? name
+        : formatMCPUIString(l.withUnit ?? DEGRADED_PROJECTION_LABELS.withUnit, { label: name, unit });
+    }),
   ];
   const rows: Array<Array<string | number>> = [];
+  const missing: boolean[][] = [];
   for (let r = 0; r < Math.min(rowCount, MAX_PROJECTED_ROWS); r++) {
     rows.push([cell(dataLabels[r] ?? r + 1), ...datasets.map((d) => cell(d.data?.[r]))]);
+    missing.push([
+      false,
+      ...datasets.map((d) => {
+        // Past the end of a shorter or empty dataset there is no entry, so
+        // nothing to flag (the cell stays empty, as before 6.24.0).
+        if (r >= (d.data?.length ?? 0)) return false;
+        const entry = d.data?.[r];
+        return (entry === null || typeof entry !== 'object') && isMissingChartValue(entry);
+      }),
+    ]);
   }
-  return { columns, rows };
+  return { columns, rows, missing };
 }

package/src/utils/iframe-coep.ts

@@ -27,14 +27,15 @@ import type { MCPUIConfig } from '../context/MCPUIConfigContext'
  *
  * An unparsable URL is not trusted, so it gets the attribute.
  *
- * Takes a RESOLVED config (`Required<MCPUIConfig>` — what `useMCPUIConfig()`
- * and `DEFAULT_MCPUI_CONFIG` hand out). `MCPUIConfig`'s own fields are
- * optional so new keys stay backward compatible, and reading an unresolved
- * one here would silently re-implement the defaults next to their source.
+ * Takes a RESOLVED config — `MCPUIConfig`, which is what `useMCPUIConfig()`
+ * and `DEFAULT_MCPUI_CONFIG` hand out, every key present. The authored view is
+ * `MCPUIConfigInput`, whose fields are optional so that a new key stays
+ * backward compatible; accepting one of those here would mean re-implementing
+ * the defaults next to their source, and silently drifting from them.
  */
 export function shouldSetCredentialless(
   url: string,
-  config: Required<MCPUIConfig>,
+  config: MCPUIConfig,
   options: { sandboxedWithoutSameOrigin: boolean }
 ): boolean {
   const mode = config.iframeCredentialless
@@ -71,7 +72,7 @@ export function createCrossOriginIsolated(): Accessor<boolean> {
  * Takes a resolved config, for the reason given on `shouldSetCredentialless`.
  */
 export function shouldShowIframeFallbackLink(
-  config: Required<MCPUIConfig>,
+  config: MCPUIConfig,
   crossOriginIsolated: boolean
 ): boolean {
   const mode = config.iframeFallbackLink

package/src/utils/math-markdown.ts

@@ -0,0 +1,222 @@
+import type { Config } from 'dompurify'
+import { Marked, Renderer, type MarkedExtension, type Tokens } from 'marked'
+import type { MathRenderer } from '../context/MCPUIMathContext'
+import { escapeHtml } from './escape-html'
+import { canSanitizeHtml, sanitizeHtml } from './sanitize-html'
+
+export type MathMarkdownProfile = 'prose' | 'cellMarkdown'
+export type MarkdownTextTransform = (escapedText: string) => string
+
+export const MATH_MARKDOWN_LIMITS = {
+  sourceLength: 100_000,
+  expressionLength: 4_096,
+  expressionCount: 128,
+} as const
+
+const MATH_TAGS = [
+  'math', 'semantics', 'mrow', 'mi', 'mo', 'mn', 'mtext', 'mspace', 'ms',
+  'msup', 'msub', 'msubsup', 'mfrac', 'msqrt', 'mroot', 'mtable', 'mtr',
+  'mtd', 'mover', 'munder', 'munderover', 'mpadded', 'mphantom', 'mstyle', 'menclose',
+] as const
+
+const MATH_ATTRS = [
+  'xmlns', 'display', 'class', 'mathvariant', 'stretchy', 'fence', 'separator',
+  'lspace', 'rspace', 'accent', 'accentunder', 'columnalign', 'rowalign',
+  'columnspacing', 'rowspacing', 'columnlines', 'rowlines', 'frame', 'notation',
+  'width', 'height', 'depth', 'voffset', 'scriptlevel', 'displaystyle',
+] as const
+
+const STRICT_MATHML_CONFIG = {
+  ALLOWED_TAGS: [...MATH_TAGS, 'span'],
+  ALLOWED_ATTR: [...MATH_ATTRS],
+  FORBID_TAGS: ['annotation', 'annotation-xml', 'style', 'a'],
+  // DOMPurify normally keeps the text of forbidden tags. TeX annotations can
+  // be large and duplicate the accessible MathML, so remove their subtree.
+  ADD_FORBID_CONTENTS: ['annotation', 'annotation-xml'],
+  FORBID_ATTR: ['style'],
+} as Config
+
+const CELL_MARKDOWN_TAGS = [
+  'a', 'strong', 'em', 'b', 'i', 'code', 'span', 'br', 'button', 'svg', 'path',
+  'p', 'ul', 'ol', 'li', 'pre', 'blockquote', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  ...MATH_TAGS,
+]
+
+const FINAL_PROFILES: Record<MathMarkdownProfile, Config> = {
+  prose: {
+    ADD_TAGS: [...MATH_TAGS],
+    ADD_ATTR: [...MATH_ATTRS, 'target', 'rel'],
+    FORBID_TAGS: ['annotation', 'annotation-xml', 'style', 'form', 'textarea', 'select', 'button', 'iframe', 'object', 'embed'],
+    ADD_FORBID_CONTENTS: ['annotation', 'annotation-xml'],
+    FORBID_ATTR: ['style'],
+  } as Config,
+  cellMarkdown: {
+    ALLOWED_TAGS: CELL_MARKDOWN_TAGS,
+    ALLOWED_ATTR: [
+      'href', 'target', 'rel', 'class', 'data-citation-page', 'data-citation-source',
+      'data-citation-doc', 'data-citation-verified', 'title', 'fill', 'stroke',
+      'viewBox', 'stroke-linecap', 'stroke-linejoin', 'stroke-width', 'd',
+      ...MATH_ATTRS,
+    ],
+    FORBID_TAGS: ['annotation', 'annotation-xml', 'style'],
+    ADD_FORBID_CONTENTS: ['annotation', 'annotation-xml'],
+    FORBID_ATTR: ['style'],
+  } as Config,
+}
+
+interface MathToken extends Tokens.Generic {
+  type: 'mcpDisplayMath' | 'mcpInlineMath'
+  raw: string
+  tex: string
+  displayMode: boolean
+  render: boolean
+}
+
+function isCurrencyLike(raw: string, tex: string, following: string): boolean {
+  if (/^\$\s|\s\$$/.test(raw)) return true
+  if (/^\d+(?:[.,]\d+)?-\s*$/.test(tex)) return true
+  if (/^\d/.test(tex) && /^\d/.test(following)) return true
+
+  // A currency opener can otherwise pair with the opening delimiter of a
+  // later expression ("$5 then ($x$)"). Reinterpret that first candidate
+  // only when it starts with a bounded numeric amount and its apparent closer
+  // is immediately followed by a complete later inline body. This deliberately
+  // leaves inherently ambiguous standalone forms ($5$, $2 + 3$, $2\pi$) as
+  // math and does not depend on the prose between the two delimiters.
+  const amount = /^\d+(?:[.,]\d{1,2})?(?=$|[\s,;:!?()[\]+*/-])/.exec(tex)?.[0]
+  if (!amount) return false
+
+  // A standalone numeric token is valid math even when followed by prose or
+  // another expression ("$5$, then $x$"). Reassignment requires content
+  // beyond the amount itself.
+  const trailing = tex.slice(amount.length)
+  if (!trailing) return false
+
+  // During streaming, the later formula may not have closed yet. An unmatched
+  // opening parenthesis before its dollar is sufficient structural evidence
+  // that the numeric dollar was currency; otherwise a permissive renderer can
+  // briefly flash "5 then (" as math.
+  const hasUnmatchedOpeningParen = (trailing.match(/\(/g)?.length ?? 0) > (trailing.match(/\)/g)?.length ?? 0)
+  const containsTexCommand = /\\[A-Za-z]+/.test(trailing)
+  if (hasUnmatchedOpeningParen && !containsTexCommand) return true
+
+  const closerLooksLikeLaterOpener = /^(?![\s,.;:!?)}\]])(?:\\[^\n]|[^\\\n$])+\$(?!\$)/.test(following)
+  return closerLooksLikeLaterOpener
+}
+
+const CELL_LINK_ATTRIBUTES = 'target="_blank" rel="noopener noreferrer" class="text-blue-600 dark:text-blue-400 hover:underline"'
+
+function cellLinkExtension(): MarkedExtension {
+  return {
+    renderer: {
+      link(this: Renderer, token: Tokens.Link): string {
+        // Marked owns escaping of the destination, title and nested label
+        // tokens. Only inject fixed attributes into its already-safe anchor.
+        const anchor = Renderer.prototype.link.call(this, token) as string
+        return anchor.replace('<a ', `<a ${CELL_LINK_ATTRIBUTES} `)
+      },
+    },
+  }
+}
+
+function mathExtension(renderer: MathRenderer): MarkedExtension {
+  let count = 0
+  const token = (raw: string, tex: string, displayMode: boolean): MathToken => ({
+    type: displayMode ? 'mcpDisplayMath' : 'mcpInlineMath',
+    raw,
+    tex,
+    displayMode,
+    render: ++count <= MATH_MARKDOWN_LIMITS.expressionCount && tex.length <= MATH_MARKDOWN_LIMITS.expressionLength,
+  })
+
+  return {
+    extensions: [
+      {
+        name: 'mcpDisplayMath',
+        level: 'block',
+        start(src) {
+          const index = src.indexOf('$$')
+          return index < 0 ? undefined : index
+        },
+        tokenizer(src) {
+          const match = /^\$\$\s*\n?([\s\S]+?)\n?\s*\$\$(?:\n|$)/.exec(src)
+          if (!match) return undefined
+          return token(match[0], match[1], true)
+        },
+        renderer(tokenValue) {
+          return renderToken(tokenValue as MathToken, renderer)
+        },
+      },
+      {
+        name: 'mcpInlineMath',
+        level: 'inline',
+        start(src) {
+          const index = src.indexOf('$')
+          return index < 0 ? undefined : index
+        },
+        tokenizer(src) {
+          const match = /^\$(?!\$)((?:\\[^\n]|[^\\\n$])+?)\$(?!\$)/.exec(src)
+          if (!match || isCurrencyLike(match[0], match[1], src.slice(match[0].length))) return undefined
+          return token(match[0], match[1], false)
+        },
+        renderer(tokenValue) {
+          return renderToken(tokenValue as MathToken, renderer)
+        },
+      },
+    ],
+  }
+}
+
+function renderToken(token: MathToken, renderer: MathRenderer): string {
+  if (!token.render) return escapeHtml(token.raw)
+  try {
+    const rendered = renderer(token.tex, { displayMode: token.displayMode })
+    if (!rendered) return escapeHtml(token.raw)
+    return sanitizeHtml(rendered, STRICT_MATHML_CONFIG)
+  } catch {
+    return escapeHtml(token.raw)
+  }
+}
+
+/**
+ * Parse Markdown with isolated, bounded math support and sanitize the complete
+ * result for its final sink. The optional transform sees escaped ordinary text
+ * tokens only. Math, code, raw HTML and link destinations never pass through
+ * it, so citation syntax cannot corrupt TeX optional arguments or attributes.
+ */
+export function parseMathMarkdown(
+  source: string,
+  renderer: MathRenderer,
+  profile: MathMarkdownProfile,
+  transformText?: MarkdownTextTransform,
+): string {
+  const input = source === null || source === undefined ? '' : String(source)
+  if (!canSanitizeHtml()) return escapeHtml(input)
+  if (input.length > MATH_MARKDOWN_LIMITS.sourceLength) return escapeHtml(input)
+
+  const textRenderer = transformText
+    ? {
+        renderer: {
+          text(this: Renderer, token: Tokens.Text | Tokens.Escape): string {
+            // Block text tokens (notably list-item text) can own already
+            // tokenized inline children. Recurse first so math and code keep
+            // their own renderers; leaf text callbacks run as parsing descends.
+            if ('tokens' in token && token.tokens) {
+              return this.parser.parseInline(token.tokens)
+            }
+            // Delegate entity handling and nested token rendering to Marked's
+            // own renderer. `escapeHtml` is deliberately not equivalent: it
+            // turns source `&amp;` into visible `&amp;` by double-escaping it.
+            const safeText = Renderer.prototype.text.call(this, token)
+            return transformText(safeText as string)
+          },
+        },
+      }
+    : undefined
+  const extensions = [mathExtension(renderer)]
+  if (profile === 'cellMarkdown') extensions.push(cellLinkExtension())
+  if (textRenderer) extensions.push(textRenderer)
+  const parser = new Marked({ gfm: true }, ...extensions)
+  const parsed = parser.parse(input, { async: false }) as string
+  return sanitizeHtml(parsed, FINAL_PROFILES[profile])
+}

package/src/utils/missing-value.ts

@@ -0,0 +1,127 @@
+/**
+ * Missing values — one definition shared by tables, chart data views,
+ * degraded projections, chart validation and the chart renderer.
+ *
+ * @since v6.24.0
+ *
+ * A missing value is a value the payload says EXISTS but was not observed:
+ * `null` in a chart dataset (or as a point's `y`), `null` / `undefined` in a
+ * table cell. It is not a zero, and it is not the absence of a row or of a
+ * label: every view keeps its slot and marks it.
+ *
+ * Runtime-free on purpose (no `solid-js`): the pure projections in
+ * `chart-data-table.ts` and `degraded-projections.ts`, and `validation.ts`
+ * (published as the `/validation` subpath), import it.
+ */
+
+/** The glyph a table cell shows for a missing value — `renderCellValue`'s historical `-`. */
+export const MISSING_VALUE_MARKER = '-'
+
+/**
+ * Chart types that encode a value as a share of a whole (or, for polar area,
+ * as a wedge whose emptiness reads as zero). Chart.js parses a `null` share
+ * as `0`, so these types refuse missing values instead of drawing them.
+ */
+export const PART_TO_WHOLE_CHART_TYPES: ReadonlySet<string> = new Set([
+  'pie',
+  'doughnut',
+  'polarArea',
+])
+
+/**
+ * Whether a raw TABLE cell value is displayed as {@link MISSING_VALUE_MARKER}.
+ *
+ * Mirrors the rules `renderCellValue` applies before any formatting — `null`,
+ * `undefined`, and a string that is empty or the word `undefined` once the
+ * backend's `"X – undefined"` debris is stripped — plus the literal marker
+ * itself (whitespace around it aside, which a table cell does not render),
+ * since it looks identical on screen and so must read identically.
+ *
+ * Objects are never missing here: `renderCellValue` renders them (link,
+ * name, or escaped JSON).
+ */
+export function isMissingCellValue(value: unknown): boolean {
+  if (value === null || value === undefined) return true
+  if (typeof value === 'object') return false
+  const cleaned = stripUndefinedDebris(String(value)).trim()
+  return cleaned === '' || cleaned === MISSING_VALUE_MARKER || cleaned.toLowerCase() === 'undefined'
+}
+
+/**
+ * Removes the `"Text – undefined"` / `"undefined – Text"` debris some
+ * backends concatenate. Shared with `renderCellValue` so both apply the very
+ * same cleanup.
+ */
+export function stripUndefinedDebris(value: string): string {
+  return value.replace(/\s*[–-]\s*undefined\s*$/gi, '').replace(/^undefined\s*[–-]\s*/gi, '')
+}
+
+/**
+ * Whether one CHART data entry is missing: `null` / `undefined`, a non-finite
+ * number (Chart.js parses those to `null` too), or a point whose `y` is.
+ */
+export function isMissingChartValue(value: unknown): boolean {
+  if (value === null || value === undefined) return true
+  if (typeof value === 'number') return !Number.isFinite(value)
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    const y = (value as { y?: unknown }).y
+    return y === null || y === undefined || (typeof y === 'number' && !Number.isFinite(y))
+  }
+  return false
+}
+
+/**
+ * What a chart's missing values amount to.
+ *
+ * Only ENTRIES count: an explicit `null` (or non-finite number, or a point
+ * whose `y` is one). A dataset with no entry at all (`data: []`) is not
+ * "missing" — it is how 6.23.0 and earlier payloads said "nothing yet", e.g.
+ * while streaming, and it keeps rendering exactly as it did then.
+ */
+export interface ChartMissingSummary {
+  /** At least one entry of one dataset is missing. */
+  hasMissing: boolean
+  /** Per dataset, in order: it has entries and every one of them is missing. */
+  fullyMissing: boolean[]
+  /**
+   * Per dataset, in order: at least one observed value AND at least one
+   * missing entry — the series a reader actually sees broken.
+   */
+  partiallyMissing: boolean[]
+  /** Something is missing and no dataset has a single observed value: nothing to plot. */
+  allMissing: boolean
+}
+
+interface ChartDataLike {
+  data?: {
+    datasets?: Array<{ data?: unknown[] } | null | undefined>
+  }
+}
+
+/** Summarises the missing values of a chart payload. Never throws on a malformed payload. */
+export function summarizeChartMissing(params: ChartDataLike | null | undefined): ChartMissingSummary {
+  const datasets = Array.isArray(params?.data?.datasets) ? params.data.datasets : []
+  const fullyMissing: boolean[] = []
+  const partiallyMissing: boolean[] = []
+  let anyMissing = false
+  let anyObserved = false
+  for (const dataset of datasets) {
+    const data = Array.isArray(dataset?.data) ? dataset.data : []
+    let observed = 0
+    let missing = 0
+    for (const value of data) {
+      if (isMissingChartValue(value)) missing += 1
+      else observed += 1
+    }
+    fullyMissing.push(missing > 0 && observed === 0)
+    partiallyMissing.push(observed > 0 && missing > 0)
+    anyMissing ||= missing > 0
+    anyObserved ||= observed > 0
+  }
+  return {
+    hasMissing: anyMissing,
+    fullyMissing,
+    partiallyMissing,
+    allMissing: anyMissing && !anyObserved,
+  }
+}