@opendata-ai/openchart-vanilla 7.2.4 → 7.4.0

package/src/measure-text.ts

@@ -4,11 +4,20 @@
  * Shared by mount.ts (charts) and sankey-mount.ts (sankey diagrams) so both
  * pipelines get accurate browser-measured text widths instead of the heuristic
  * fallback. Falls back to the heuristic when canvas isn't available (e.g. SSR).
+ *
+ * The font family is passed in (resolved from the container's --oc-font-family
+ * or the spec theme) rather than hardcoded, so measurement matches what the SVG
+ * text actually renders with. This matters on real devices where the primary
+ * webfont (e.g. Inter) loads late: measuring against the wrong font produces
+ * wrong widths and mangles layout.
  */
 
 import type { MeasureTextFn } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+
+const DEFAULT_FONT_FAMILY = 'Inter, sans-serif';
 
-export function createMeasureText(): MeasureTextFn {
+export function createMeasureText(fontFamily: string = DEFAULT_FONT_FAMILY): MeasureTextFn {
   let canvas: HTMLCanvasElement | null = null;
   let ctx: CanvasRenderingContext2D | null = null;
 
@@ -23,11 +32,14 @@ export function createMeasureText(): MeasureTextFn {
     }
     if (!ctx) {
       // Fallback: heuristic estimation
-      return { width: text.length * fontSize * 0.6, height: fontSize * 1.2 };
+      return {
+        width: estimateTextWidth(text, fontSize, fontWeight ?? 400),
+        height: fontSize * 1.2,
+      };
     }
 
     const weight = fontWeight ?? 400;
-    ctx.font = `${weight} ${fontSize}px Inter, sans-serif`;
+    ctx.font = `${weight} ${fontSize}px ${fontFamily}`;
     const metrics = ctx.measureText(text);
     return {
       width: metrics.width,
@@ -35,3 +47,88 @@ export function createMeasureText(): MeasureTextFn {
     };
   };
 }
+
+/**
+ * Resolve the font family a container's SVG text will actually render with.
+ *
+ * Reads the --oc-font-family custom property (set by tokens.css once .oc-root
+ * is applied, or overridden per-spec by the theme resolver), falling back to
+ * the container's computed fontFamily, then to the default Inter stack. Returns
+ * the previous hardcoded stack when there is no DOM (SSR) or no computed style.
+ */
+export function resolveFontFamily(container: HTMLElement): string {
+  if (typeof window === 'undefined' || typeof getComputedStyle !== 'function') {
+    return DEFAULT_FONT_FAMILY;
+  }
+  try {
+    const style = getComputedStyle(container);
+    const custom = style.getPropertyValue('--oc-font-family').trim();
+    if (custom) return custom;
+    const computed = style.fontFamily?.trim();
+    if (computed) return computed;
+  } catch {
+    // getComputedStyle can throw on detached nodes in some engines; fall through.
+  }
+  return DEFAULT_FONT_FAMILY;
+}
+
+/**
+ * The first family in a CSS font stack, with surrounding quotes stripped, e.g.
+ * `'"Inter Variable", Inter, sans-serif'` -> `Inter Variable`. Used to build a
+ * representative check string for document.fonts.check().
+ */
+export function primaryFontName(fontFamily: string): string {
+  const first = fontFamily.split(',')[0]?.trim() ?? '';
+  return first.replace(/^["']|["']$/g, '').trim();
+}
+
+/**
+ * True when the primary font of the resolved stack is not yet loaded and a
+ * later document.fonts.ready may change text metrics. False when fonts are
+ * ready, unavailable (SSR / no FontFaceSet), or the primary is a generic family.
+ */
+export function fontsPending(fontFamily: string): boolean {
+  if (typeof document === 'undefined') return false;
+  const fonts = (document as Document & { fonts?: FontFaceSet }).fonts;
+  if (!fonts || typeof fonts.check !== 'function') return false;
+  const name = primaryFontName(fontFamily);
+  if (!name) return false;
+  const generics = new Set([
+    'sans-serif',
+    'serif',
+    'monospace',
+    'system-ui',
+    'cursive',
+    'fantasy',
+    'ui-sans-serif',
+    'ui-serif',
+    'ui-monospace',
+  ]);
+  if (generics.has(name.toLowerCase())) return false;
+  try {
+    return !fonts.check(`12px "${name}"`);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run `onReady` exactly once after webfonts finish loading, if they were
+ * pending at call time. `isAlive` is checked before invoking so a destroyed
+ * chart is never re-rendered. Returns the initial pending state so callers can
+ * set their `ocFontsState` dataset flag. No-op (returns false) under SSR or
+ * when the primary font is already loaded.
+ */
+export function scheduleFontReload(
+  fontFamily: string,
+  isAlive: () => boolean,
+  onReady: () => void,
+): boolean {
+  if (!fontsPending(fontFamily)) return false;
+  const fonts = (document as Document & { fonts?: FontFaceSet }).fonts;
+  if (!fonts?.ready) return false;
+  fonts.ready.then(() => {
+    if (isAlive()) onReady();
+  });
+  return true;
+}

package/src/mount.ts

@@ -53,7 +53,7 @@ import {
   wireTooltipEvents,
   wireVoronoiTooltipEvents,
 } from './interactions';
-import { createMeasureText } from './measure-text';
+import { createMeasureText, resolveFontFamily, scheduleFontReload } from './measure-text';
 import { observeResize } from './resize-observer';
 import { renderChartSVG } from './svg-renderer';
 import { createTextEditOverlay } from './text-edit-overlay';
@@ -190,6 +190,13 @@ export function createChart<TData extends DataRow = DataRow>(
   let cleanupAnimations: (() => void) | null = null;
   let pendingResize = false;
 
+  // Set when webfonts have loaded and a recompile is owed to reflect final font
+  // metrics. The next render() that actually recompiles flips
+  // data-oc-fonts-state to 'ready' and clears this. Deferring the flip (rather
+  // than setting it right after resize()) keeps the attribute honest when the
+  // entrance animation makes resize() defer to pendingResize.
+  let fontsReloadPending = false;
+
   // Selection and text editing state
   let selectedElement: ElementRef | null = options?.selectedElement ?? null;
   let overlayElement: SVGGElement | null = null;
@@ -200,7 +207,25 @@ export function createChart<TData extends DataRow = DataRow>(
   const runtimeShownSeries = new Set<string>();
   let textEditCleanup: (() => void) | null = null;
 
-  const measureText = createMeasureText();
+  // Apply the root class up front so getComputedStyle can read --oc-font-family
+  // before we build the text measurer.
+  container.classList.add('oc-root');
+
+  // Resolve the effective font family the way compile() will. compile merges
+  // { ...spec.theme, ...options.theme }, so options.theme wins over the
+  // spec-level theme; fall back to the container's computed font. Measuring
+  // against a different font than compile renders (e.g. a spec that sets
+  // theme.fonts.family) desyncs layout metrics and the font-reload watcher.
+  function resolveEffectiveFont(): string {
+    return (
+      options?.theme?.fonts?.family ??
+      currentSpec.theme?.fonts?.family ??
+      resolveFontFamily(container)
+    );
+  }
+  let fontFamily = resolveEffectiveFont();
+  let measureText = createMeasureText(fontFamily);
+  let renderGen = 0;
 
   // ---------------------------------------------------------------------------
   // Compilation
@@ -774,6 +799,20 @@ export function createChart<TData extends DataRow = DataRow>(
         }
       });
     }
+    // Bump the render generation so tests (and consumers) can observe every
+    // full recompile, including the post-font-load one.
+    renderGen += 1;
+    container.dataset.ocRenderGen = String(renderGen);
+
+    // This render recompiled with the loaded webfonts, so the layout now
+    // reflects final font metrics. Publish 'ready' only now (not right after
+    // the fonts-ready resize(), which may have deferred to pendingResize while
+    // the entrance animation was still running).
+    if (fontsReloadPending) {
+      fontsReloadPending = false;
+      container.dataset.ocFontsState = 'ready';
+    }
+
     if (isFirstRender) {
       isFirstRender = false;
     }
@@ -786,6 +825,13 @@ export function createChart<TData extends DataRow = DataRow>(
   function update(newSpec: ChartSpec | GraphSpec, updateOpts?: UpdateOptions): void {
     if (destroyed) return;
     currentSpec = newSpec;
+    // A new spec can change theme.fonts.family; rebuild the measurer so layout
+    // measures the font compile will actually render with.
+    const nextFont = resolveEffectiveFont();
+    if (nextFont !== fontFamily) {
+      fontFamily = nextFont;
+      measureText = createMeasureText(fontFamily);
+    }
     runtimeHiddenSeries.clear();
     runtimeShownSeries.clear();
     if (updateOpts && 'selectedElement' in updateOpts) {
@@ -893,6 +939,23 @@ export function createChart<TData extends DataRow = DataRow>(
   // Initial render
   render();
 
+  // Recompile once after webfonts load. On real devices the primary font
+  // (e.g. Inter via display=swap) often swaps in after first paint, changing
+  // text metrics; without a re-measure, titles wrap wrong and labels collide.
+  // Desktop Chrome has the font cached, so it renders 'ready' immediately.
+  const pending = scheduleFontReload(
+    fontFamily,
+    () => !destroyed,
+    () => {
+      // Mark the reload owed, then trigger a recompile. render() flips the
+      // attribute to 'ready' once it actually recompiles — including the
+      // pendingResize replay after the entrance animation finishes.
+      fontsReloadPending = true;
+      resize();
+    },
+  );
+  container.dataset.ocFontsState = pending ? 'pending' : 'ready';
+
   // Set up responsive resize
   if (options?.responsive !== false) {
     disconnectResize = observeResize(container, () => {

package/src/renderers/annotations.ts

@@ -214,14 +214,7 @@ function renderAnnotation(
     const lineHeight = fontSize * (annotation.label.style.lineHeight ?? 1.3);
     const isMultiLine = lines.length > 1;
 
-    // Multi-line text: drop-line connectors keep the resolved side anchor so
-    // the label hugs the vertical line. Other connectors center the text for
-    // a cleaner look.
     if (isMultiLine) {
-      const isDropLine = annotation.label.connector?.style === 'drop-line';
-      if (!isDropLine) {
-        text.setAttribute('text-anchor', 'middle');
-      }
       for (let i = 0; i < lines.length; i++) {
         const tspan = createSVGElement('tspan');
         setAttrs(tspan, { x: annotation.label.x, dy: i === 0 ? 0 : lineHeight });
@@ -235,20 +228,35 @@ function renderAnnotation(
     // Render background rect behind text if specified, otherwise use
     // paint-order stroke halo to knock out lines behind text
     if (annotation.label.background) {
-      const charWidth = fontSize * 0.55;
-      const maxLineWidth = Math.max(...lines.map((l) => l.length)) * charWidth;
-      const totalHeight = lines.length * lineHeight;
       const pad = 3;
-      const bgX = isMultiLine
-        ? annotation.label.x - maxLineWidth / 2 - pad
-        : annotation.label.x - pad;
+      let bgX: number;
+      let bgY: number;
+      let bgW: number;
+      let bgH: number;
+
+      if (annotation.label.bounds) {
+        const b = annotation.label.bounds;
+        bgX = b.x - pad;
+        bgY = b.y - pad;
+        bgW = b.width + pad * 2;
+        bgH = b.height + pad * 2;
+      } else {
+        const charWidth = fontSize * 0.55;
+        const maxLineWidth = Math.max(...lines.map((l) => l.length)) * charWidth;
+        const totalHeight = lines.length * lineHeight;
+        bgX = isMultiLine ? annotation.label.x - maxLineWidth / 2 - pad : annotation.label.x - pad;
+        bgY = annotation.label.y - fontSize + (lineHeight - fontSize) / 2 - pad;
+        bgW = maxLineWidth + pad * 2;
+        bgH = totalHeight + pad * 2;
+      }
+
       const bgRect = createSVGElement('rect');
       bgRect.setAttribute('class', 'oc-annotation-bg');
       setAttrs(bgRect, {
         x: bgX,
-        y: annotation.label.y - fontSize + (lineHeight - fontSize) / 2 - pad,
-        width: maxLineWidth + pad * 2,
-        height: totalHeight + pad * 2,
+        y: bgY,
+        width: bgW,
+        height: bgH,
         fill: annotation.label.background,
         rx: 2,
       });

package/src/renderers/axes.ts

@@ -8,6 +8,7 @@ import {
   estimateTextWidth,
   getAxisTitleOffset,
   TICK_LABEL_OFFSET,
+  textAscent,
 } from '@opendata-ai/openchart-core';
 import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
 
@@ -86,16 +87,15 @@ function renderAxis(
         });
       } else {
         const xLabelPad = axis.labelPadding ?? layout.theme.spacing.xAxisLabelPadding;
-        // Anchor at the text's top edge (hanging baseline) so xLabelPad is the
-        // literal gap between the axis line and the top of the label, regardless
-        // of font size. With the default alphabetic baseline the offset lands at
-        // the text baseline instead, so large fonts let the label top creep up
-        // and hug (or overlap) the axis line.
+        // xLabelPad is the literal gap between the axis line and the TOP of
+        // the label regardless of font size, so shift down by the ascent to
+        // land on the alphabetic baseline. (dominant-baseline:hanging would
+        // express this directly, but WebKit positions hanging from different
+        // font metrics than Blink, drifting labels on iOS Safari.)
         setAttrs(label, {
           x: tick.position,
-          y: area.y + area.height + xLabelPad,
+          y: area.y + area.height + xLabelPad + textAscent(axis.tickLabelStyle.fontSize),
           'text-anchor': 'middle',
-          'dominant-baseline': 'hanging',
         });
       }
 
@@ -242,9 +242,18 @@ function renderAxis(
     applyTextStyle(axisLabel, axis.labelStyle);
     axisLabel.textContent = axis.label;
 
-    if (orientation === 'x') {
-      // Position axis title below tick labels. For rotated labels, compute
-      // the vertical extent of the rotated ticks and place the title below.
+    const tp = axis.titlePosition;
+    if (tp) {
+      const attrs: Record<string, string | number> = {
+        x: tp.x,
+        y: tp.y,
+        'text-anchor': 'middle',
+      };
+      if (tp.angle) {
+        attrs.transform = `rotate(${tp.angle}, ${tp.x}, ${tp.y})`;
+      }
+      setAttrs(axisLabel, attrs);
+    } else if (orientation === 'x') {
       let titleY = area.y + area.height + 35;
       if (axis.tickAngle && Math.abs(axis.tickAngle) > 10) {
         const angleRad = Math.abs(axis.tickAngle) * (Math.PI / 180);
@@ -266,7 +275,6 @@ function renderAxis(
         'text-anchor': 'middle',
       });
     } else if (isRight) {
-      // Rotated right y-axis label (tighter offset on compact viewports)
       const titleOffset = getAxisTitleOffset(layout.dimensions.width);
       const titleX = area.x + area.width + titleOffset;
       setAttrs(axisLabel, {
@@ -276,11 +284,6 @@ function renderAxis(
         transform: `rotate(90, ${titleX}, ${area.y + area.height / 2})`,
       });
     } else {
-      // Rotated left y-axis label.
-      // Compute a dynamic offset so the title clears the widest tick label.
-      // The title is rotated and centered, so axisTitleOffset() adds its own
-      // half-glyph height on top of the gap (otherwise large title fonts overlap
-      // the tick labels — the gap is visible clearance, not center-to-edge).
       const maxTickLabelWidth = axis.ticks.reduce((max, t) => {
         const w = estimateTextWidth(
           t.label,

package/src/renderers/brand.ts

@@ -3,8 +3,8 @@
  */
 
 import type { ChartLayout } from '@opendata-ai/openchart-core';
-import { BRAND_FONT_SIZE, BRAND_MIN_WIDTH } from '@opendata-ai/openchart-core';
-import { computeXAxisExtent, createSVGElement, setAttrs, XLINK_NS } from './svg-dom';
+import { BRAND_FONT_SIZE, BRAND_MIN_WIDTH, textAscent } from '@opendata-ai/openchart-core';
+import { createSVGElement, setAttrs, XLINK_NS } from './svg-dom';
 
 const BRAND_URL = 'https://tryopendata.ai';
 
@@ -24,8 +24,7 @@ export function renderBrand(parent: SVGElement, layout: ChartLayout): void {
 
   // Vertically align with the first bottom chrome element.
   const { chrome } = layout;
-  const xAxisExtent = computeXAxisExtent(layout);
-  const bottomOffset = layout.area.y + layout.area.height + xAxisExtent;
+  const bottomOffset = chrome.bottomAnchorY ?? layout.area.y + layout.area.height;
   const firstBottom = chrome.source ?? chrome.byline ?? chrome.footer;
   // When no bottom chrome items exist, derive a fallback offset that still
   // clears any bottom-positioned legend so the brand watermark doesn't
@@ -46,13 +45,15 @@ export function renderBrand(parent: SVGElement, layout: ChartLayout): void {
 
   // "try" in normal weight, "OpenData" in semibold, ".ai" in normal weight,
   // rendered as a single right-aligned text element with three tspans.
-  // Use hanging baseline to align top-edge with source/byline chrome text.
+  // chromeY is the top edge shared with source/byline chrome text; anchor the
+  // shared alphabetic baseline from the largest tspan's ascent. (Hanging
+  // baseline is avoided: WebKit positions it differently and never inherits
+  // it into tspans, which scattered the three spans on iOS Safari.)
   const BRAND_LARGE = 16;
   const text = createSVGElement('text');
   setAttrs(text, {
     x: rightEdge,
-    y: chromeY,
-    'dominant-baseline': 'hanging',
+    y: chromeY + textAscent(BRAND_LARGE),
     'font-family': layout.theme.fonts.family,
     'font-size': BRAND_FONT_SIZE,
     'text-anchor': 'end',

package/src/renderers/chrome.ts

@@ -7,8 +7,8 @@ import type {
   MeasureTextFn,
   ResolvedChromeElement,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
-import { applyTextStyle, computeXAxisExtent, createSVGElement, setAttrs } from './svg-dom';
+import { estimateTextWidth, textAscent, wrapText } from '@opendata-ai/openchart-core';
+import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
 
 function renderChromeElement(
   parent: SVGElement,
@@ -19,7 +19,10 @@ function renderChromeElement(
   uppercase = false,
 ): void {
   const text = createSVGElement('text');
-  setAttrs(text, { x: element.x, y: element.y });
+  // element.y is the TOP of the text box; convert to the alphabetic baseline
+  // here instead of relying on dominant-baseline:hanging, which WebKit
+  // positions from different font metrics and never inherits into tspans.
+  setAttrs(text, { x: element.x, y: element.y + textAscent(element.style.fontSize) });
   applyTextStyle(text, element.style);
   text.setAttribute('class', className);
   text.setAttribute('data-chrome-key', chromeKey);
@@ -61,8 +64,8 @@ export function renderChrome(parent: SVGElement, layout: ChartLayout): void {
   // Top chrome: render at their stored y positions (already absolute)
   if (chrome.eyebrow) {
     // Leading accent dot — matches the editorial design system mock.
-    // Eyebrow text uses dominantBaseline: hanging, so eyebrow.y is the top of
-    // the text. Visual center is roughly y + fontSize * 0.55 (cap height).
+    // eyebrow.y is the top of the text box. Visual center is roughly
+    // y + fontSize * 0.55 (cap height).
     const eyebrow = chrome.eyebrow;
     const dotR = 3;
     const dotGap = 8;
@@ -87,10 +90,7 @@ export function renderChrome(parent: SVGElement, layout: ChartLayout): void {
     renderChromeElement(g, chrome.subtitle, 'oc-subtitle', 'subtitle', measureText);
   }
 
-  // Bottom chrome starts below x-axis labels/title, not at chart area bottom.
-  // Accounts for rotated tick labels which need more vertical space.
-  const xAxisExtent = computeXAxisExtent(layout);
-  const bottomOffset = layout.area.y + layout.area.height + xAxisExtent;
+  const bottomOffset = layout.chrome.bottomAnchorY ?? layout.area.y + layout.area.height;
   if (chrome.source) {
     renderChromeElement(
       g,

package/src/renderers/legend.ts

@@ -19,14 +19,18 @@ export function renderLegend(parent: SVGElement, legend: LegendLayout): void {
   g.setAttribute('aria-label', 'Chart legend');
 
   const isHorizontal = legend.position === 'top' || legend.position === 'bottom';
+  const positions = 'entryPositions' in legend ? legend.entryPositions : undefined;
   let offsetX = legend.bounds.x;
   let offsetY = legend.bounds.y;
 
   for (let i = 0; i < legend.entries.length; i++) {
     const entry = legend.entries[i];
 
-    // Pre-check: wrap to next line if this entry would overflow bounds
-    if (isHorizontal && i > 0) {
+    const pos = positions?.[i];
+    if (pos) {
+      offsetX = pos.x;
+      offsetY = pos.y;
+    } else if (isHorizontal && i > 0) {
       const labelWidth = estimateTextWidth(
         entry.label,
         legend.labelStyle.fontSize,
@@ -116,17 +120,21 @@ export function renderLegend(parent: SVGElement, legend: LegendLayout): void {
 
     g.appendChild(entryG);
 
-    // Advance position for next entry
-    if (isHorizontal) {
-      const labelWidth = estimateTextWidth(
-        entry.label,
-        legend.labelStyle.fontSize,
-        legend.labelStyle.fontWeight,
-      );
-      const entryWidth = legend.swatchSize + legend.swatchGap + labelWidth + legend.entryGap;
-      offsetX += entryWidth;
-    } else {
-      offsetY += legend.swatchSize + legend.entryGap;
+    if (!pos) {
+      if (isHorizontal) {
+        const labelWidth = estimateTextWidth(
+          entry.label,
+          legend.labelStyle.fontSize,
+          legend.labelStyle.fontWeight,
+        );
+        const entryWidth = legend.swatchSize + legend.swatchGap + labelWidth + legend.entryGap;
+        offsetX += entryWidth;
+      } else {
+        offsetY +=
+          'rowHeight' in legend && legend.rowHeight
+            ? legend.rowHeight
+            : legend.swatchSize + legend.entryGap;
+      }
     }
   }
 

package/src/renderers/svg-dom.ts

@@ -4,8 +4,7 @@
  * Pure, stateless utilities. No layout/theme knowledge.
  */
 
-import type { ChartLayout, TextStyle } from '@opendata-ai/openchart-core';
-import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import type { TextStyle } from '@opendata-ai/openchart-core';
 
 export const SVG_NS = 'http://www.w3.org/2000/svg';
 export const XLINK_NS = 'http://www.w3.org/1999/xlink';
@@ -39,28 +38,3 @@ export function applyTextStyle(el: SVGElement, style: TextStyle): void {
     el.setAttribute('font-variant', style.fontVariant);
   }
 }
-
-/**
- * Compute the vertical extent of x-axis labels below the chart area.
- * Accounts for rotated tick labels which need more vertical space.
- */
-export function computeXAxisExtent(layout: ChartLayout): number {
-  const xAxis = layout.axes.x;
-  if (!xAxis) return 0;
-
-  if (xAxis.tickAngle && Math.abs(xAxis.tickAngle) > 10) {
-    // Rotated labels: estimate height from the longest tick label.
-    const fontSize = xAxis.tickLabelStyle.fontSize;
-    const fontWeight = xAxis.tickLabelStyle.fontWeight;
-    const angleRad = Math.abs(xAxis.tickAngle) * (Math.PI / 180);
-    let maxLabelWidth = 40;
-    for (const tick of xAxis.ticks) {
-      const w = estimateTextWidth(tick.label, fontSize, fontWeight);
-      if (w > maxLabelWidth) maxLabelWidth = w;
-    }
-    const rotatedHeight = Math.min(maxLabelWidth * Math.sin(angleRad) + 6, 120);
-    return xAxis.label ? rotatedHeight + 20 : rotatedHeight;
-  }
-
-  return xAxis.label ? 48 : 26;
-}

package/src/sankey-mount.ts

@@ -23,7 +23,7 @@ import {
   type JPGExportOptions,
   type SVGExportOptions,
 } from './export';
-import { createMeasureText } from './measure-text';
+import { createMeasureText, resolveFontFamily, scheduleFontReload } from './measure-text';
 import { observeResize } from './resize-observer';
 import { renderSankeySVG } from './sankey-renderer';
 import { createTooltipManager, type TooltipManager } from './tooltip';
@@ -122,7 +122,30 @@ export function createSankey(
   let animationCleanup: (() => void) | null = null;
   let pendingResize = false;
 
-  const measureText = createMeasureText();
+  // Set when webfonts have loaded and a recompile is owed. The next render()
+  // that recompiles flips data-oc-fonts-state to 'ready' and clears this, so
+  // the attribute stays honest when resize() defers to pendingResize during
+  // the entrance animation.
+  let fontsReloadPending = false;
+
+  // Apply the root class up front so getComputedStyle sees --oc-font-family
+  // before the text measurer is built.
+  container.classList.add('oc-sankey-root');
+
+  // Resolve the effective font the way compile() will: compile merges
+  // { ...spec.theme, ...options.theme }, so options.theme wins over the
+  // spec-level theme; fall back to the container's computed font. Measuring a
+  // different font than gets rendered desyncs layout metrics and the reload watcher.
+  function resolveEffectiveFont(): string {
+    return (
+      options?.theme?.fonts?.family ??
+      currentSpec.theme?.fonts?.family ??
+      resolveFontFamily(container)
+    );
+  }
+  let fontFamily = resolveEffectiveFont();
+  let measureText = createMeasureText(fontFamily);
+  let renderGen = 0;
 
   // ---------------------------------------------------------------------------
   // Helpers
@@ -410,6 +433,17 @@ export function createSankey(
         }
       });
     }
+
+    renderGen += 1;
+    container.dataset.ocRenderGen = String(renderGen);
+
+    // This render recompiled with the loaded webfonts; publish 'ready' now
+    // rather than right after the fonts-ready resize() (which may have deferred
+    // to pendingResize during the entrance animation).
+    if (fontsReloadPending) {
+      fontsReloadPending = false;
+      container.dataset.ocFontsState = 'ready';
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -419,6 +453,13 @@ export function createSankey(
   function update(newSpec: SankeySpec): void {
     if (destroyed) return;
     currentSpec = newSpec;
+    // A new spec can change theme.fonts.family; rebuild the measurer so layout
+    // measures the font compile will actually render with.
+    const nextFont = resolveEffectiveFont();
+    if (nextFont !== fontFamily) {
+      fontFamily = nextFont;
+      measureText = createMeasureText(fontFamily);
+    }
     isFirstRender = true; // Allow animation on update
     render();
   }
@@ -495,6 +536,7 @@ export function createSankey(
     svgElement = null;
 
     container.classList.remove('oc-dark');
+    container.classList.remove('oc-sankey-root');
   }
 
   // ---------------------------------------------------------------------------
@@ -537,12 +579,30 @@ export function createSankey(
         }
       });
     }
+
+    renderGen += 1;
+    container.dataset.ocRenderGen = String(renderGen);
   } catch (err) {
     console.error('[viz] Sankey mount failed:', err);
     // Re-throw so callers can handle the error rather than silently returning a broken instance
     throw err;
   }
 
+  // Recompile once after webfonts load so late-swapping fonts don't leave
+  // node labels measured against fallback metrics.
+  const fontsPending = scheduleFontReload(
+    fontFamily,
+    () => !destroyed,
+    () => {
+      // Mark the reload owed, then recompile. render() flips the attribute to
+      // 'ready' once it actually recompiles, including the pendingResize replay
+      // after the entrance animation finishes.
+      fontsReloadPending = true;
+      resize();
+    },
+  );
+  container.dataset.ocFontsState = fontsPending ? 'pending' : 'ready';
+
   // Responsive resize
   if (options?.responsive !== false) {
     disconnectResize = observeResize(container, () => {