@opendata-ai/openchart-engine 8.9.0 → 8.9.1

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/compile.ts
+import { mergeThemeConfig as mergeThemeConfig6 } from "@opendata-ai/openchart-core";
+
 // src/design/diagnostics.ts
 import { computeLabelBounds, contrastRatio, isOpaqueColor } from "@opendata-ai/openchart-core";
 
@@ -76,6 +79,18 @@ function linkedEntityKeys(row, source, target) {
 }
 
 // src/design/diagnostics.ts
+function noteCapacityDiagnostic(layout) {
+  if ((layout.chrome.noteBandHeight ?? 0) <= 0 || layout.area.height > 0) return void 0;
+  return {
+    code: "layout.note-capacity",
+    path: "/annotations",
+    origin: "author",
+    status: "failed",
+    severity: "error",
+    viewport: layout.dimensions,
+    message: 'Reserved annotation note capacity leaves no plotting space. Increase the requested height, explicitly choose chromeLayout: "grow", or reduce annotation text/count.'
+  };
+}
 function diagnoseChart(spec, layout) {
   const diagnostics = [];
   const viewport = layout.dimensions;
@@ -176,7 +191,9 @@ function diagnoseChart(spec, layout) {
       "author"
     );
   }
-  if (layout.area.width < 80 || layout.area.height < 80)
+  const exhaustedNotes = noteCapacityDiagnostic(layout);
+  if (exhaustedNotes) diagnostics.push(exhaustedNotes);
+  else if (layout.area.width < 80 || layout.area.height < 80)
     emit(
       "layout.constrained",
       "/chromeLayout",
@@ -205,17 +222,17 @@ function diagnoseChart(spec, layout) {
 import {
   adaptTheme as adaptTheme6,
   computeLabelBounds as computeLabelBounds2,
-  footnoteBandHeight,
+  computeNoteBandHeight as computeNoteBandHeight2,
   generateAltText,
   generateDataTable,
-  getBreakpoint as getBreakpoint3,
-  getHeightClass as getHeightClass3,
-  getLayoutStrategy,
+  getBreakpoint as getBreakpoint4,
+  getHeightClass as getHeightClass4,
+  getLayoutStrategy as getLayoutStrategy2,
   isAxislessMark as isAxislessMark3,
   MAX_SR_TABLE_ROWS,
   resolveChromeEconomy,
   resolveTheme as resolveTheme7,
-  wrapText as wrapText3
+  wrapText as wrapText4
 } from "@opendata-ai/openchart-core";
 
 // src/annotations/collisions.ts
@@ -408,7 +425,7 @@ function estimateLabelBounds(label, measure = heuristicMeasure) {
   return computeTextBlockBounds(
     label.x,
     label.y,
-    label.text,
+    label.lines?.join("\n") ?? label.text,
     {
       fontSize,
       fontWeight,
@@ -436,19 +453,38 @@ function computeArrowheadPoints(tipX, tipY, tangentX, tangentY, length = ARROWHE
 function connectorPullbackGap(markerRadius, arrow) {
   return arrow ? Math.max(markerRadius + 2, 2) : Math.max(markerRadius + 3, 4);
 }
-function refreshConnector(connector, bounds, markerRadius) {
+function automaticControlPoint(from, to, exit, bend = 0) {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const vertical = exit ? exit === "vertical" : Math.abs(dy) >= Math.abs(dx);
+  const x = from.x + dx * (vertical ? 0.2 : 0.6);
+  const y = from.y + dy * (vertical ? 0.6 : 0.2);
+  return bend === 0 ? { x, y } : { x: x + bend * dy, y: y - bend * dx };
+}
+function refreshConnector(connector, bounds, markerRadius, keepVisible = false) {
   if (!connector.endpoint) return void 0;
   const endpoint = connector.endpoint;
   if (connector.style === "drop-line") {
     const gap2 = connectorPullbackGap(markerRadius, false);
     return {
       ...connector,
-      from: { x: endpoint.x, y: bounds.y - DROP_LINE_TOP_GAP },
+      from: {
+        x: endpoint.x + (connector.fromOffset?.dx ?? 0),
+        y: bounds.y - DROP_LINE_TOP_GAP + (connector.fromOffset?.dy ?? 0)
+      },
       to: { x: endpoint.x, y: endpoint.y - gap2 },
       exit: "vertical"
     };
   }
-  const exit = connectorExit(bounds, endpoint.x, endpoint.y);
+  const exit = (connector.labelAttachment === "left-center" ? {
+    x: bounds.x - BOX_INFLATE - CONNECTOR_STANDOFF,
+    y: bounds.y + bounds.height / 2,
+    exit: "horizontal"
+  } : connectorExit(bounds, endpoint.x, endpoint.y)) ?? (keepVisible ? {
+    x: bounds.x + bounds.width / 2,
+    y: bounds.y + bounds.height / 2,
+    exit: connector.exit ?? "horizontal"
+  } : null);
   if (!exit) return void 0;
   const from = {
     x: exit.x + (connector.fromOffset?.dx ?? 0),
@@ -461,8 +497,15 @@ function refreshConnector(connector, bounds, markerRadius) {
   const to = dist > 0 ? { x: endpoint.x - cdx / dist * gap, y: endpoint.y - cdy / dist * gap } : { ...endpoint };
   const lx = to.x - from.x;
   const ly = to.y - from.y;
-  if (!connectorIsDrawable(Math.sqrt(lx * lx + ly * ly), connector.arrow)) return void 0;
-  return { ...connector, from, to, exit: exit.exit };
+  if (!keepVisible && !connectorIsDrawable(Math.sqrt(lx * lx + ly * ly), connector.arrow))
+    return void 0;
+  return {
+    ...connector,
+    from,
+    to,
+    exit: exit.exit,
+    ...connector.style === "curve" ? { control: automaticControlPoint(from, to, exit.exit, connector.bend) } : {}
+  };
 }
 
 // src/annotations/position.ts
@@ -542,12 +585,76 @@ function resolvePositionEdge(value, scale, edge) {
   return center;
 }
 
+// src/annotations/wrap-text.ts
+function wrapAnnotationText(text, maxWidth, style, measure) {
+  const width = (chars) => {
+    let total = 0;
+    let run = "";
+    let bold = false;
+    const flush = () => {
+      total += measure(run, {
+        fontSize: style.fontSize,
+        fontWeight: bold ? BOLD_SPAN_FONT_WEIGHT : Number(style.fontWeight) || 400
+      });
+    };
+    for (const char of chars) {
+      if (char.bold !== bold) {
+        flush();
+        run = "";
+        bold = char.bold;
+      }
+      run += char.text;
+    }
+    flush();
+    return total;
+  };
+  const serialize = (chars) => {
+    let result = "";
+    let bold = false;
+    for (const char of chars) {
+      if (char.bold !== bold) {
+        result += "**";
+        bold = char.bold;
+      }
+      result += char.text;
+    }
+    return result + (bold ? "**" : "");
+  };
+  return text.split("\n").flatMap((paragraph) => {
+    const chars = parseAnnotationSpans(paragraph).flatMap(
+      (span) => Array.from(span.text, (text2) => ({ text: text2, bold: span.bold }))
+    );
+    const lines = [];
+    let pending = [];
+    for (const char of chars) {
+      pending.push(char);
+      if (width(pending) <= maxWidth || pending.length === 1) continue;
+      let split = -1;
+      for (let i = pending.length - 1; i > 0; i--)
+        if (/\s/.test(pending[i].text)) {
+          split = i;
+          break;
+        }
+      if (split > 0) {
+        lines.push(serialize(pending.slice(0, split)));
+        pending = pending.slice(split + 1);
+      } else {
+        const last = pending.pop();
+        lines.push(serialize(pending));
+        pending = [last];
+      }
+    }
+    if (pending.length || !lines.length) lines.push(serialize(pending));
+    return lines;
+  });
+}
+
 // src/annotations/resolve-text.ts
-function defaultConnectorStroke(hasArrow, isDark, textInk) {
+function defaultConnectorStroke(hasArrow, isDark, textInk, colors) {
   if (hasArrow) return textInk;
-  return isDark ? DARK_CONNECTOR_STROKE : LIGHT_CONNECTOR_STROKE;
+  return colors?.annotationLeader ?? (isDark ? DARK_CONNECTOR_STROKE : LIGHT_CONNECTOR_STROKE);
 }
-function resolveDot(dotSpec, hasConnector, hasArrow, x, y, isDark, connectorStroke) {
+function resolveDot(dotSpec, hasConnector, hasArrow, x, y, isDark, connectorStroke, colors) {
   const useDefault = dotSpec === void 0 && hasConnector && !hasArrow;
   if (!dotSpec && !useDefault) return void 0;
   const dotConfig = typeof dotSpec === "object" ? dotSpec : {};
@@ -555,7 +662,7 @@ function resolveDot(dotSpec, hasConnector, hasArrow, x, y, isDark, connectorStro
     x,
     y,
     radius: dotConfig.radius ?? DEFAULT_DOT_RADIUS,
-    fill: dotConfig.fill ?? (isDark ? DARK_DOT_FILL : LIGHT_DOT_FILL),
+    fill: dotConfig.fill ?? colors?.annotationMarkerFill ?? (isDark ? DARK_DOT_FILL : LIGHT_DOT_FILL),
     stroke: dotConfig.stroke ?? connectorStroke,
     strokeWidth: dotConfig.strokeWidth ?? DEFAULT_DOT_STROKE_WIDTH
   };
@@ -568,15 +675,50 @@ function resolveConnectorConfig(connector) {
   if (typeof connector === "object" && connector !== null && "type" in connector) {
     const cfg = connector;
     const arrow = cfg.type === "drop-line" ? false : cfg.arrow ?? cfg.type === "curve";
-    return { type: cfg.type, arrow };
+    return {
+      type: cfg.type,
+      arrow,
+      ...cfg.type === "curve" && cfg.bend !== void 0 ? { bend: cfg.bend } : {}
+    };
   }
   if (connector === "curve") return { type: "curve", arrow: true };
   if (connector === "drop-line") return { type: "drop-line", arrow: false };
   return { type: "straight", arrow: false };
 }
-function resolveLabelBackground(background, isDark) {
+function textConnectorSeed(annotation, scales, isDark, colors) {
+  const config = resolveConnectorConfig(annotation.connector);
+  const x = resolvePosition(annotation.x, scales.x);
+  const y = resolvePosition(annotation.y, scales.y);
+  if (!config || x === null || y === null) return void 0;
+  const endpoint = {
+    x: x + (annotation.connectorOffset?.to?.dx ?? 0),
+    y: y + (annotation.connectorOffset?.to?.dy ?? 0)
+  };
+  return {
+    from: { ...endpoint },
+    to: { ...endpoint },
+    endpoint,
+    style: config.type,
+    arrow: config.arrow,
+    stroke: annotation.stroke ?? defaultConnectorStroke(
+      config.arrow,
+      isDark,
+      annotation.fill ?? colors?.annotationLabel ?? (isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL),
+      colors
+    ),
+    ...config.bend !== void 0 ? { bend: config.bend } : {},
+    ...annotation.connectorOffset?.from ? {
+      fromOffset: {
+        dx: annotation.connectorOffset.from.dx ?? 0,
+        dy: annotation.connectorOffset.from.dy ?? 0
+      }
+    } : {}
+  };
+}
+function resolveLabelBackground(background, isDark, colors) {
   if (background === void 0) return void 0;
-  if (background === true) return isDark ? DARK_LABEL_BACKGROUND : LIGHT_LABEL_BACKGROUND;
+  if (background === true)
+    return colors?.annotationPlate ?? (isDark ? DARK_LABEL_BACKGROUND : LIGHT_LABEL_BACKGROUND);
   return background;
 }
 var DROP_LINE_LABEL_GAP = 8;
@@ -595,12 +737,58 @@ function resolveLedeFontWeight(annotation) {
   if (annotation.fontWeight !== void 0) return annotation.fontWeight;
   return annotation.subtitle ? LEDE_FONT_WEIGHT : void 0;
 }
-function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure = heuristicMeasure, fontFamily) {
+function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure = heuristicMeasure, fontFamily, colors) {
+  if (annotation.maxWidth == null)
+    return resolveTextAnnotationDisplay(
+      annotation,
+      scales,
+      chartArea,
+      isDark,
+      measure,
+      fontFamily,
+      colors
+    );
+  const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+  const lines = wrapAnnotationText(
+    annotation.text,
+    annotation.maxWidth,
+    { fontSize, fontWeight: resolveLedeFontWeight(annotation) },
+    measure
+  );
+  const subLines = annotation.subtitle ? wrapAnnotationText(
+    annotation.subtitle,
+    annotation.maxWidth,
+    {
+      fontSize: annotation.subtitleFontSize ?? subtitleFontSize(fontSize),
+      fontWeight: SUBTITLE_FONT_WEIGHT
+    },
+    measure
+  ) : void 0;
+  const resolved = resolveTextAnnotationDisplay(
+    { ...annotation, text: lines.join("\n"), subtitle: subLines?.join("\n") },
+    scales,
+    chartArea,
+    isDark,
+    measure,
+    fontFamily,
+    colors
+  );
+  if (resolved?.label) {
+    resolved.label.text = annotation.text;
+    resolved.label.lines = lines;
+  }
+  if (resolved?.subtitle) {
+    resolved.subtitle.text = annotation.subtitle;
+    resolved.subtitle.lines = subLines;
+  }
+  return resolved;
+}
+function resolveTextAnnotationDisplay(annotation, scales, chartArea, isDark, measure = heuristicMeasure, fontFamily, colors) {
   const px = resolvePosition(annotation.x, scales.x);
   const py = resolvePosition(annotation.y, scales.y);
   if (px === null || py === null) return null;
-  const defaultTextFill = isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL;
-  const labelBackground = resolveLabelBackground(annotation.background, isDark);
+  const defaultTextFill = colors?.annotationLabel ?? (isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL);
+  const labelBackground = resolveLabelBackground(annotation.background, isDark, colors);
   const labelStyle = makeAnnotationLabelStyle(
     annotation.fontSize,
     resolveLedeFontWeight(annotation),
@@ -618,7 +806,8 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
       labelStyle,
       labelBackground,
       isDark,
-      measure
+      measure,
+      colors
     );
   }
   labelStyle.textAnchor = annotation.anchor === "left" ? "end" : "start";
@@ -640,7 +829,7 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
       annotation.subtitle,
       {
         ...labelStyle,
-        fontSize: subtitleFontSize(fontSize),
+        fontSize: annotation.subtitleFontSize ?? subtitleFontSize(fontSize),
         fontWeight: SUBTITLE_FONT_WEIGHT,
         textAnchor: "start"
       },
@@ -658,10 +847,10 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
   let annotationBounds = labelBounds;
   if (annotation.subtitle) {
     const primaryLineCount = annotation.text.split("\n").length;
-    const mutedFill = isDark ? DARK_MUTED_TEXT_FILL : LIGHT_MUTED_TEXT_FILL;
+    const mutedFill = colors?.annotationMuted ?? (isDark ? DARK_MUTED_TEXT_FILL : LIGHT_MUTED_TEXT_FILL);
     const subtitleStyle = {
       ...labelStyle,
-      fontSize: subtitleFontSize(fontSize),
+      fontSize: annotation.subtitleFontSize ?? subtitleFontSize(fontSize),
       fontWeight: SUBTITLE_FONT_WEIGHT,
       fill: mutedFill
     };
@@ -685,7 +874,7 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
     x: px + (annotation.connectorOffset?.to?.dx ?? 0),
     y: py + (annotation.connectorOffset?.to?.dy ?? 0)
   };
-  const connectorStroke = annotation.stroke ?? defaultConnectorStroke(connectorArrow, isDark, labelStyle.fill ?? defaultTextFill);
+  const connectorStroke = annotation.stroke ?? defaultConnectorStroke(connectorArrow, isDark, labelStyle.fill ?? defaultTextFill, colors);
   const dot = resolveDot(
     annotation.dot,
     showConnector,
@@ -693,7 +882,8 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
     endpoint.x,
     endpoint.y,
     isDark,
-    connectorStroke
+    connectorStroke,
+    colors
   );
   let connector;
   if (showConnector) {
@@ -722,7 +912,11 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
           stroke: connectorStroke,
           style: connectorStyle,
           arrow: connectorArrow,
-          exit: exit.exit
+          exit: exit.exit,
+          ...connectorStyle === "curve" ? {
+            control: automaticControlPoint(from, to, exit.exit, connectorConfig?.bend),
+            ...connectorConfig?.bend !== void 0 ? { bend: connectorConfig.bend } : {}
+          } : {}
         };
       }
     }
@@ -751,12 +945,12 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
     bounds: annotationBounds
   };
 }
-function resolveDropLineAnnotation(annotation, px, py, chartArea, labelStyle, labelBackground, isDark, measure = heuristicMeasure) {
+function resolveDropLineAnnotation(annotation, px, py, chartArea, labelStyle, labelBackground, isDark, measure = heuristicMeasure, colors) {
   const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = Number(labelStyle.fontWeight) || DEFAULT_ANNOTATION_FONT_WEIGHT;
   const lines = annotation.text.split("\n");
   const subtitleLines = annotation.subtitle ? annotation.subtitle.split("\n") : [];
-  const subFontSize = subtitleFontSize(fontSize);
+  const subFontSize = annotation.subtitleFontSize ?? subtitleFontSize(fontSize);
   const estimatedWidth = Math.max(
     0,
     ...lines.map((line4) => measureRichLine(line4, { fontSize, fontWeight }, measure)),
@@ -774,21 +968,37 @@ function resolveDropLineAnnotation(annotation, px, py, chartArea, labelStyle, la
   } else if (side === "right" && !fitsRight) {
     side = fitsLeft || spaceLeft > spaceRight ? "left" : "right";
   }
-  const labelX = side === "left" ? px - DROP_LINE_LABEL_GAP : px + DROP_LINE_LABEL_GAP;
+  const labelX = (side === "left" ? px - DROP_LINE_LABEL_GAP : px + DROP_LINE_LABEL_GAP) + (annotation.offset?.dx ?? 0);
   const textAnchor = side === "left" ? "end" : "start";
   const lineHeight = fontSize * DEFAULT_LINE_HEIGHT;
   const subtitleHeight = annotation.subtitle ? SUBTITLE_GAP + subFontSize * DEFAULT_LINE_HEIGHT * subtitleLines.length : 0;
   const totalHeight = lineHeight * lines.length + subtitleHeight;
   const desiredLabelTopY = py - totalHeight - 12;
   const minLabelTopY = chartArea.y + 4;
-  const labelTopY = Math.max(desiredLabelTopY, minLabelTopY);
+  const labelTopY = Math.max(desiredLabelTopY, minLabelTopY) + (annotation.offset?.dy ?? 0);
   const labelBaselineY = labelTopY + fontSize;
   const resolvedStyle = { ...labelStyle, textAnchor };
-  const connectorStroke = annotation.stroke ?? (isDark ? DARK_CONNECTOR_STROKE : LIGHT_CONNECTOR_STROKE);
-  const dot = resolveDot(annotation.dot, true, false, px, py, isDark, connectorStroke);
+  const connectorStroke = annotation.stroke ?? colors?.annotationLeader ?? (isDark ? DARK_CONNECTOR_STROKE : LIGHT_CONNECTOR_STROKE);
+  const endpoint = {
+    x: px + (annotation.connectorOffset?.to?.dx ?? 0),
+    y: py + (annotation.connectorOffset?.to?.dy ?? 0)
+  };
+  const dot = resolveDot(
+    annotation.dot,
+    true,
+    false,
+    endpoint.x,
+    endpoint.y,
+    isDark,
+    connectorStroke,
+    colors
+  );
   const bottomGap = connectorPullbackGap(markerClearance(dot), false);
-  const from = { x: px, y: labelTopY - DROP_LINE_TOP_GAP };
-  const to = { x: px, y: py - bottomGap };
+  const from = {
+    x: endpoint.x + (annotation.connectorOffset?.from?.dx ?? 0),
+    y: labelTopY - DROP_LINE_TOP_GAP + (annotation.connectorOffset?.from?.dy ?? 0)
+  };
+  const to = { x: endpoint.x, y: endpoint.y - bottomGap };
   const labelBounds = computeTextBlockBounds(
     labelX,
     labelBaselineY,
@@ -803,7 +1013,7 @@ function resolveDropLineAnnotation(annotation, px, py, chartArea, labelStyle, la
       ...resolvedStyle,
       fontSize: subFontSize,
       fontWeight: SUBTITLE_FONT_WEIGHT,
-      fill: isDark ? DARK_MUTED_TEXT_FILL : LIGHT_MUTED_TEXT_FILL
+      fill: colors?.annotationMuted ?? (isDark ? DARK_MUTED_TEXT_FILL : LIGHT_MUTED_TEXT_FILL)
     };
     const subtitleY = subtitleBaselineY(labelBaselineY, lineHeight, lines.length);
     subtitle = {
@@ -826,7 +1036,13 @@ function resolveDropLineAnnotation(annotation, px, py, chartArea, labelStyle, la
     connector: {
       from,
       to,
-      endpoint: { x: px, y: py },
+      endpoint,
+      ...annotation.connectorOffset?.from ? {
+        fromOffset: {
+          dx: annotation.connectorOffset.from.dx ?? 0,
+          dy: annotation.connectorOffset.from.dy ?? 0
+        }
+      } : {},
       stroke: connectorStroke,
       style: "drop-line",
       arrow: false,
@@ -860,7 +1076,7 @@ function annotationBlockBounds(annotation, label, measure) {
   const subBounds = computeTextBlockBounds(
     sub.x,
     sub.y,
-    sub.text,
+    sub.lines?.join("\n") ?? sub.text,
     {
       // Every resolver stamps all three, so these fallbacks are unreachable today.
       // They still come from the constants: a hand-rolled `?? 10` here is a second
@@ -1033,9 +1249,6 @@ function sampleAreaObstacles(topPoints, bottomPoints, bucketWidth = 24, pad = 3)
   }
   return [...lineObs, ...fillObs];
 }
-function normalizeObstacles(rects, kind = "mark") {
-  return rects.map((r) => ({ ...r, kind }));
-}
 var OBSTACLE_WEIGHTS = {
   annotation: 30,
   line: 20,
@@ -1293,7 +1506,7 @@ function findBestPlacement(anchorX, anchorY, text, style, subtitleText, subtitle
   };
 }
 function isAutoPlacement(annotation) {
-  if (annotation.offset) return false;
+  if (annotation.offset !== void 0) return false;
   if (annotation.anchor && annotation.anchor !== "auto") return false;
   if (annotation.connector === "drop-line") return false;
   if (typeof annotation.connector === "object" && annotation.connector !== null && annotation.connector.type === "drop-line")
@@ -1318,8 +1531,7 @@ function generateNudgeCandidates(selfBounds, obstacles, padding) {
   return candidates;
 }
 function hasExplicitOffset(annotation) {
-  const moved = (annotation.offset?.dx ?? 0) !== 0 || (annotation.offset?.dy ?? 0) !== 0;
-  return moved && !isAutoPlacement(annotation);
+  return annotation.offset !== void 0 && !isAutoPlacement(annotation);
 }
 function nudgeAnnotationFromObstacles(annotation, originalAnnotation, scales, chartArea, obstacles, measure = heuristicMeasure) {
   if (annotation.type !== "text" || !annotation.label) return false;
@@ -1530,8 +1742,310 @@ function collectPinnedOverlapWarnings(annotations, specs, obstacles, measure = h
   return warnings;
 }
 
+// src/annotations/edit-context.ts
+import { annotationSource } from "@opendata-ai/openchart-core";
+var geometry = /* @__PURE__ */ new WeakMap();
+function rememberAnnotationGeometry(annotation, authored, context) {
+  geometry.set(annotation, { context, authored });
+}
+var snapshots = /* @__PURE__ */ new WeakMap();
+function createAnnotationEditContext(layout, spec) {
+  const source = annotationSource(spec);
+  const entries = [];
+  const panels = layout.facet ? layout.facet.panels.map((p) => ({ annotations: p.annotations, facet: p.key })) : [{ annotations: layout.annotations, facet: void 0 }];
+  for (const panel of panels) {
+    for (const resolved of panel.annotations) {
+      if (resolved.type !== "text" || !resolved.label || !resolved.bounds) continue;
+      const metadata = geometry.get(resolved);
+      if (!metadata || !source) continue;
+      const index = resolved.specIndex;
+      if (index === void 0) continue;
+      const authored = source.annotations[index];
+      if (!authored || authored.type !== "text" || authored.id !== resolved.id) continue;
+      const context = metadata.context;
+      const anchor = resolved.label.style.textAnchor === "end" ? "left" : "right";
+      const base = resolveTextAnnotation(
+        { ...metadata.authored, anchor, offset: void 0 },
+        context.scales,
+        context.chartArea,
+        context.isDark,
+        context.measure,
+        context.fontFamily,
+        context.colors
+      );
+      if (!base) continue;
+      entries.push({
+        ref: {
+          type: "annotation",
+          index,
+          id: authored.id,
+          path: `${source.path}/${index}`,
+          ...panel.facet !== void 0 ? { facetInstance: panel.facet } : {}
+        },
+        resolved: structuredClone(resolved),
+        base,
+        anchor,
+        connectorSeed: textConnectorSeed(
+          metadata.authored,
+          context.scales,
+          context.isDark,
+          context.colors
+        ),
+        context: {
+          ...context,
+          chartArea: { ...context.chartArea },
+          svg: { ...context.svg },
+          obstacles: []
+        }
+      });
+    }
+  }
+  const snapshot = Object.freeze({ kind: "annotation-edit-context" });
+  snapshots.set(snapshot, entries);
+  return snapshot;
+}
+function entryFor(ctx, ref) {
+  if (ref.type !== "annotation") throw new Error("Expected an annotation reference");
+  const matches = (snapshots.get(ctx) ?? []).filter(
+    (entry) => entry.ref.index === ref.index && (ref.id === void 0 || entry.ref.id === ref.id) && (ref.path === void 0 || ref.path === entry.ref.path || ref.path.startsWith(`${entry.ref.path}/`)) && (ref.facetInstance === void 0 || ref.facetInstance === entry.ref.facetInstance)
+  );
+  if (matches.length !== 1)
+    throw new Error("Annotation reference is missing or ambiguous in this edit context");
+  return matches[0];
+}
+function inverseLabelPlacement(ctx, ref, renderedBox) {
+  const entry = entryFor(ctx, ref);
+  const bounds = entry.base.bounds;
+  return {
+    anchor: entry.anchor,
+    offset: {
+      dx: Math.round((renderedBox.x - bounds.x) * 1e10) / 1e10,
+      dy: Math.round((renderedBox.y - bounds.y) * 1e10) / 1e10
+    },
+    responsive: false
+  };
+}
+function previewAnnotationMove(ctx, ref, delta) {
+  const entry = entryFor(ctx, ref);
+  const annotation = structuredClone(entry.resolved);
+  const context = entry.context;
+  if (!annotation.label.connector && entry.connectorSeed)
+    annotation.label.connector = structuredClone(entry.connectorSeed);
+  moveAnnotationBy(annotation, annotation.label, delta.dx, delta.dy, context.measure);
+  clampAnnotationsToBounds(
+    [annotation],
+    context.svg.width,
+    context.svg.height,
+    context.measure,
+    context.topBound
+  );
+  return annotation;
+}
+function previewConnectorBend(ctx, ref, bend) {
+  if (!Number.isFinite(bend) || bend < -1 || bend > 1)
+    throw new RangeError("Connector bend must be between -1 and 1");
+  const annotation = structuredClone(entryFor(ctx, ref).resolved);
+  const connector = annotation.label?.connector;
+  if (connector?.style === "curve")
+    annotation.label.connector = refreshConnector(
+      { ...connector, bend },
+      annotation.bounds,
+      markerClearance(annotation.dot)
+    );
+  return annotation;
+}
+function previewConnectorOffset(ctx, ref, end, delta) {
+  const entry = entryFor(ctx, ref);
+  const annotation = structuredClone(entry.resolved);
+  const connector = structuredClone(annotation.label?.connector ?? entry.connectorSeed);
+  if (!connector?.endpoint) return annotation;
+  if (end === "from")
+    connector.fromOffset = {
+      dx: (connector.fromOffset?.dx ?? 0) + delta.dx,
+      dy: (connector.fromOffset?.dy ?? 0) + delta.dy
+    };
+  else {
+    connector.endpoint.x += delta.dx;
+    connector.endpoint.y += delta.dy;
+    if (annotation.dot) {
+      annotation.dot.x += delta.dx;
+      annotation.dot.y += delta.dy;
+    }
+  }
+  annotation.label.connector = refreshConnector(
+    connector,
+    annotation.bounds,
+    markerClearance(annotation.dot)
+  );
+  return annotation;
+}
+
+// src/annotations/reference-layout.ts
+import { overlapArea as overlapArea3 } from "@opendata-ai/openchart-core";
+function referenceLabelReserve(annotations, width, measure) {
+  const outside = annotations.filter(
+    (a) => a.type === "refline" && a.labelPlacement === "outside" && !!a.label
+  );
+  const labelWidth = Math.max(24, Math.min(160, width * 0.25));
+  const vertical = outside.filter((a) => a.y === void 0);
+  const top = vertical.reduce(
+    (height, a) => height + wrapAnnotationText(
+      a.label,
+      labelWidth,
+      { fontSize: a.fontSize ?? 11, fontWeight: a.fontWeight ?? 400 },
+      measure
+    ).length * (a.fontSize ?? 11) * 1.3 + 8,
+    0
+  );
+  return {
+    right: outside.some((a) => a.y !== void 0) ? labelWidth + 32 : 0,
+    top: top ? top + 24 : 0,
+    labelWidth
+  };
+}
+function placeReferenceLabel(annotation, resolved, area3, container, reserve, lanes, measure, colors, warn, obstacles = []) {
+  const label = resolved.label;
+  const line4 = resolved.line;
+  if (!label || !line4 || !annotation.labelPlacement) return;
+  const horizontal = annotation.y !== void 0;
+  const initial = { x: label.x, y: label.y };
+  const bounds = () => estimateLabelBounds(label, measure);
+  const fits = (box) => box.x >= container.x && box.y >= container.y && box.x + box.width <= container.x + container.width && box.y + box.height <= container.y + container.height;
+  let target = horizontal ? line4.end : line4.start;
+  if (annotation.labelOffset !== void 0) {
+    if (!fits(bounds()))
+      warn?.(
+        "[openchart] Reference labelOffset pins an overflowing label; remove labelOffset to allow automatic containment."
+      );
+  } else if (annotation.labelPlacement === "outside") {
+    label.lines = wrapAnnotationText(
+      label.text,
+      reserve.labelWidth,
+      { fontSize: label.style.fontSize, fontWeight: label.style.fontWeight },
+      measure
+    );
+    label.style = { ...label.style, textAnchor: "start" };
+    const size = bounds();
+    if (horizontal) {
+      label.x = container.x + container.width - reserve.right + 24;
+      const previous = lanes.rightLabels?.at(-1)?.bounds;
+      const top = Math.max(
+        area3.y,
+        line4.end.y - size.height / 2,
+        previous ? previous.y + previous.height + 8 : area3.y
+      );
+      label.y += top - bounds().y;
+      resolved.bounds = bounds();
+      (lanes.rightLabels ??= []).push(resolved);
+      const bottom = Math.min(container.y + container.height, area3.y + area3.height);
+      let nextTop = bottom + 8;
+      for (const item of [...lanes.rightLabels].reverse()) {
+        const box = estimateLabelBounds(item.label, measure);
+        const dy = Math.min(0, nextTop - 8 - box.y - box.height);
+        item.label.y += dy;
+        item.bounds = item.label.bounds = estimateLabelBounds(item.label, measure);
+        nextTop = item.bounds.y;
+        if (item.label.connector)
+          item.label.connector = refreshConnector(item.label.connector, item.bounds, 0);
+      }
+      if (nextTop < area3.y)
+        warn?.(
+          "[openchart] Outside reference labels exceed their available lane; use shorter labels or a taller figure."
+        );
+    } else {
+      label.x = Math.min(
+        container.x + container.width - size.width,
+        Math.max(area3.x, line4.start.x - size.width / 2)
+      );
+      const top = lanes.topBottom ?? area3.y - reserve.top;
+      label.y += top - bounds().y;
+      lanes.topBottom = top + size.height + 8;
+    }
+  } else if (annotation.labelPlacement === "auto") {
+    const original = { x: label.x, y: label.y, anchor: label.style.textAnchor };
+    const candidates = horizontal ? [
+      { x: line4.end.x - 4, y: label.y, anchor: "end" },
+      { x: line4.start.x + 4, y: label.y, anchor: "start" }
+    ] : [
+      { x: label.x, y: line4.start.y + 14, anchor: label.style.textAnchor },
+      { x: label.x, y: line4.end.y - 4, anchor: label.style.textAnchor }
+    ];
+    const relevant = obstacles.filter((o) => o.kind !== "area-fill");
+    const clear = (box) => fits(box) && relevant.every((o) => overlapArea3(box, o) === 0);
+    let found = false;
+    for (const candidate of candidates) {
+      Object.assign(label, { x: candidate.x, y: candidate.y });
+      label.style = { ...label.style, textAnchor: candidate.anchor };
+      if (clear(bounds())) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      Object.assign(label, { x: original.x, y: original.y });
+      label.style = { ...label.style, textAnchor: original.anchor };
+      const box = bounds();
+      const shifts = horizontal ? [
+        container.x - box.x,
+        container.x + container.width - box.x - box.width,
+        ...relevant.flatMap((o) => [o.x - box.x - box.width - 4, o.x + o.width - box.x + 4])
+      ] : [
+        container.y - box.y,
+        container.y + container.height - box.y - box.height,
+        ...relevant.flatMap((o) => [o.y - box.y - box.height - 4, o.y + o.height - box.y + 4])
+      ];
+      for (const shift of [...new Set(shifts)].sort((a, b) => Math.abs(a) - Math.abs(b)).slice(0, 64)) {
+        label.x = original.x + (horizontal ? shift : 0);
+        label.y = original.y + (horizontal ? 0 : shift);
+        if (clear(bounds())) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        label.x = original.x;
+        label.y = original.y;
+        const shift = horizontal ? Math.max(
+          container.x - box.x,
+          Math.min(0, container.x + container.width - box.x - box.width)
+        ) : Math.max(
+          container.y - box.y,
+          Math.min(0, container.y + container.height - box.y - box.height)
+        );
+        if (horizontal) label.x += shift;
+        else label.y += shift;
+        warn?.(
+          '[openchart] Reference label has no clear contained position; use labelPlacement: "outside" or shorter text.'
+        );
+      }
+    }
+  }
+  label.background = colors?.annotationPlate;
+  label.bounds = bounds();
+  resolved.bounds = label.bounds;
+  if (annotation.labelPlacement === "outside" || Math.hypot(label.x - initial.x, label.y - initial.y) > 8) {
+    if (annotation.labelPlacement !== "outside")
+      target = horizontal ? { x: initial.x, y: line4.start.y } : { x: line4.start.x, y: initial.y };
+    label.connector = refreshConnector(
+      {
+        from: { ...target },
+        to: { ...target },
+        endpoint: { ...target },
+        stroke: resolved.stroke ?? "#666666",
+        style: "straight",
+        arrow: false,
+        // The whole leader stays left of the right-gutter text, even when a
+        // tall neighbor displaces this label. Persist through sweep/tween rebuilds.
+        ...annotation.labelPlacement === "outside" && horizontal && annotation.labelOffset === void 0 ? { labelAttachment: "left-center" } : {}
+      },
+      label.bounds,
+      0
+    );
+  }
+}
+
 // src/annotations/resolve-range.ts
-function resolveRangeAnnotation(annotation, scales, chartArea, isDark, fontFamily) {
+function resolveRangeAnnotation(annotation, scales, chartArea, isDark, fontFamily, colors) {
   let x = chartArea.x;
   let y = chartArea.y;
   let width = chartArea.width;
@@ -1563,7 +2077,7 @@ function resolveRangeAnnotation(annotation, scales, chartArea, isDark, fontFamil
     const style = makeAnnotationLabelStyle(
       annotation.fontSize ?? 11,
       annotation.fontWeight ?? 500,
-      void 0,
+      colors?.annotationLabel,
       isDark,
       fontFamily
     );
@@ -1587,7 +2101,7 @@ function resolveRangeAnnotation(annotation, scales, chartArea, isDark, fontFamil
     id: annotation.id,
     rect,
     label,
-    fill: annotation.fill ?? DEFAULT_RANGE_FILL,
+    fill: annotation.fill ?? colors?.annotationRangeFill ?? DEFAULT_RANGE_FILL,
     opacity: annotation.opacity ?? defaultOpacity,
     stroke: annotation.stroke,
     zIndex: annotation.zIndex
@@ -1595,7 +2109,7 @@ function resolveRangeAnnotation(annotation, scales, chartArea, isDark, fontFamil
 }
 
 // src/annotations/resolve-refline.ts
-function resolveRefLineAnnotation(annotation, scales, chartArea, isDark, measure = heuristicMeasure, fontFamily) {
+function resolveRefLineAnnotation(annotation, scales, chartArea, isDark, measure = heuristicMeasure, fontFamily, colors) {
   let start;
   let end;
   if (annotation.y !== void 0) {
@@ -1669,8 +2183,24 @@ function resolveRefLineAnnotation(annotation, scales, chartArea, isDark, measure
         textAnchor = "start";
       }
     }
+    if (annotation.labelPlacement) {
+      const atStart = annotation.labelPlacement === "start" || !isHorizontal && annotation.labelPlacement !== "end";
+      if (isHorizontal) {
+        labelX = atStart ? start.x : end.x;
+        labelY = start.y;
+        baseDx = atStart ? 4 : -4;
+        baseDy = anchor === "bottom" ? 14 : -4;
+        textAnchor = atStart ? "start" : "end";
+      } else {
+        labelX = start.x;
+        labelY = atStart ? start.y : end.y;
+        baseDx = anchor === "right" ? -4 : 4;
+        baseDy = atStart ? 14 : -4;
+        textAnchor = anchor === "right" ? "end" : "start";
+      }
+    }
     const labelDelta = applyOffset({ dx: baseDx, dy: baseDy }, annotation.labelOffset);
-    const defaultStroke2 = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
+    const defaultStroke2 = colors?.annotationRule ?? (isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE);
     const style = makeAnnotationLabelStyle(
       annotation.fontSize ?? 11,
       annotation.fontWeight ?? 400,
@@ -1687,7 +2217,7 @@ function resolveRefLineAnnotation(annotation, scales, chartArea, isDark, measure
       visible: true
     };
   }
-  const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
+  const defaultStroke = colors?.annotationRule ?? (isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE);
   const resolved = {
     type: "refline",
     id: annotation.id,
@@ -1705,24 +2235,12 @@ function resolveRefLineAnnotation(annotation, scales, chartArea, isDark, measure
 }
 
 // src/annotations/compute.ts
-function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obstacles, svgDimensions) {
-  let ctx;
-  if ("measure" in scalesOrCtx) {
-    ctx = scalesOrCtx;
-  } else {
-    ctx = {
-      scales: scalesOrCtx,
-      chartArea,
-      strategy,
-      isDark: isDark ?? false,
-      obstacles: obstacles ? normalizeObstacles(obstacles) : [],
-      svg: svgDimensions ?? { width: 0, height: 0 },
-      measure: heuristicMeasure
-    };
-  }
+function computeAnnotations(spec, ctx) {
   const isCompact = ctx.strategy.annotationPosition === "tooltip-only" && !ctx.autoThin;
   const svgRect = { x: 0, y: 0, width: ctx.svg.width, height: ctx.svg.height };
   const annotations = [];
+  const referenceReserve = ctx.referenceReserve ?? referenceLabelReserve(spec.annotations, ctx.svg.width, ctx.measure);
+  const referenceLanes = ctx.referenceLanes ?? {};
   const autoQueue = [];
   for (const [specIndex, annotation] of spec.annotations.entries()) {
     if (isCompact && annotation.responsive !== false) {
@@ -1737,7 +2255,8 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
           ctx.chartArea,
           ctx.isDark,
           ctx.measure,
-          ctx.fontFamily
+          ctx.fontFamily,
+          ctx.colors
         );
         if (resolved && ctx.svg.width > 0 && ctx.svg.height > 0 && isAutoPlacement(annotation)) {
           const px = resolvePosition(annotation.x, ctx.scales.x);
@@ -1762,7 +2281,8 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
           ctx.scales,
           ctx.chartArea,
           ctx.isDark,
-          ctx.fontFamily
+          ctx.fontFamily,
+          ctx.colors
         );
         break;
       case "refline":
@@ -1772,7 +2292,8 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
           ctx.chartArea,
           ctx.isDark,
           ctx.measure,
-          ctx.fontFamily
+          ctx.fontFamily,
+          ctx.colors
         );
         break;
     }
@@ -1787,7 +2308,30 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
           ctx.measure
         );
       }
-      if (annotation.type === "refline" && ctx.obstacles.length > 0) {
+      if (annotation.type === "refline" && annotation.labelPlacement)
+        placeReferenceLabel(
+          annotation,
+          resolved,
+          ctx.chartArea,
+          ctx.referenceContainer ?? {
+            x: 8,
+            y: ctx.topBound ?? 8,
+            width: ctx.svg.width - 16,
+            height: ctx.svg.height - (ctx.topBound ?? 8) - 8
+          },
+          referenceReserve,
+          referenceLanes,
+          ctx.measure,
+          ctx.colors,
+          ctx.onWarn,
+          [
+            ...ctx.obstacles,
+            ...annotations.flatMap(
+              (a) => a.bounds ? [{ ...a.bounds, kind: "annotation" }] : []
+            )
+          ]
+        );
+      if (annotation.type === "refline" && !annotation.labelPlacement && ctx.obstacles.length > 0) {
         nudgeRefLineLabel(resolved, annotation, ctx.obstacles, ctx.chartArea, ctx.measure);
       }
       resolved.specIndex = specIndex;
@@ -1812,7 +2356,7 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
         ctx.fontFamily
       );
       const subtitleStyle = annotation.subtitle ? {
-        fontSize: subtitleFontSize(labelStyle.fontSize),
+        fontSize: annotation.subtitleFontSize ?? subtitleFontSize(labelStyle.fontSize),
         fontWeight: SUBTITLE_FONT_WEIGHT,
         lineHeight: labelStyle.lineHeight,
         fontFamily: labelStyle.fontFamily
@@ -1820,14 +2364,14 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
       const result = findBestPlacement(
         anchorX,
         anchorY,
-        annotation.text,
+        resolved.label?.lines?.join("\n") ?? annotation.text,
         {
           fontSize: labelStyle.fontSize,
           fontWeight: Number(labelStyle.fontWeight) || 400,
           lineHeight: labelStyle.lineHeight,
           fontFamily: labelStyle.fontFamily
         },
-        annotation.subtitle,
+        resolved.subtitle?.lines?.join("\n") ?? annotation.subtitle,
         subtitleStyle,
         workingObstacles,
         ctx.chartArea,
@@ -1848,19 +2392,6 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
       const placedBounds = resolved.bounds ?? result.bounds;
       workingObstacles.push({ ...placedBounds, kind: "annotation" });
     }
-  } else if (autoQueue.length > 0) {
-    for (const entry of autoQueue) {
-      if (ctx.obstacles.length > 0) {
-        nudgeAnnotationFromObstacles(
-          entry.resolved,
-          entry.annotation,
-          ctx.scales,
-          ctx.chartArea,
-          ctx.obstacles,
-          ctx.measure
-        );
-      }
-    }
   }
   const autoIndices = new Set(autoQueue.map((q) => q.index));
   resolveAnnotationCollisions(
@@ -1875,15 +2406,73 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
     clampAnnotationsToBounds(annotations, ctx.svg.width, ctx.svg.height, ctx.measure, ctx.topBound);
   }
   annotations.sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
+  for (const resolved of annotations) {
+    const authored = spec.annotations[resolved.specIndex];
+    if (authored?.type === "text") rememberAnnotationGeometry(resolved, authored, ctx);
+  }
   return annotations;
 }
 
+// src/annotations/notes.ts
+import { estimateTextWidth as estimateTextWidth2, wrapText } from "@opendata-ai/openchart-core";
+function wrapAnnotationNotes(notes, width, theme, measureText) {
+  const size = theme.fonts.sizes.small;
+  const weight = theme.fonts.weights.normal;
+  const maxWidth = Math.max(1, width - 2 * theme.spacing.padding);
+  const measure = (text) => measureText?.(text, size, weight).width ?? estimateTextWidth2(text, size, weight);
+  return notes.map((note) => {
+    const text = `${note.index}. ${note.text}`;
+    const lines = wrapText(text, size, weight, maxWidth, measureText).flatMap((line4) => {
+      const chunks = [];
+      let chunk = "";
+      for (const character of line4) {
+        if (chunk && measure(chunk + character) > maxWidth) {
+          chunks.push(chunk);
+          chunk = character;
+        } else chunk += character;
+      }
+      chunks.push(chunk);
+      return chunks;
+    });
+    return lines.length > 1 ? { ...note, lines } : note;
+  });
+}
+function annotationNoteLineCount(notes) {
+  return notes.reduce((count, note) => count + (note.lines?.length ?? 1), 0);
+}
+function annotationNoteCapacity(annotations, width, theme, measureText, includeSingle = false) {
+  if (annotations.length <= 1 && !includeSingle) return 0;
+  const texts = annotations.flatMap(
+    (annotation, specIndex) => annotation.type === "text" ? [
+      {
+        specIndex,
+        text: annotation.subtitle ? `${annotation.text}. ${annotation.subtitle}` : annotation.text
+      }
+    ] : []
+  );
+  const size = theme.fonts.sizes.small;
+  const weight = theme.fonts.weights.normal;
+  const measure = (text) => measureText?.(text, size, weight).width ?? estimateTextWidth2(text, size, weight);
+  let widestIndex = 1;
+  for (let index = 2; index <= texts.length; index++) {
+    if (measure(`${index}. `) > measure(`${widestIndex}. `)) widestIndex = index;
+  }
+  return annotationNoteLineCount(
+    wrapAnnotationNotes(
+      texts.map((note) => ({ ...note, index: widestIndex })),
+      width,
+      theme,
+      measureText
+    )
+  );
+}
+
 // src/annotations/thinning.ts
 import { detectCollision as detectCollision2 } from "@opendata-ai/openchart-core";
 var COVERAGE_BUDGET = 0.1;
 var COLLISION_PADDING = 4;
-function thinAnnotations(annotations, specs, measure, plotArea, containerBounds) {
-  if (annotations.length <= 1) {
+function thinAnnotations(annotations, specs, measure, plotArea, containerBounds, compactLimit) {
+  if (annotations.length <= 1 && compactLimit == null) {
     return { annotations, footnotes: [] };
   }
   const entries = annotations.map((a, i) => {
@@ -1924,9 +2513,10 @@ function thinAnnotations(annotations, specs, measure, plotArea, containerBounds)
   const coverageBudget = plotAreaSize * COVERAGE_BUDGET;
   const containment = containerBounds ?? plotArea;
   let usedArea = 0;
-  for (const entry of candidates) {
+  for (const [rank, entry] of candidates.entries()) {
+    const overLimit = compactLimit != null && rank >= compactLimit;
     const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label, measure);
-    if (bounds.width <= 0 || bounds.height <= 0) {
+    if (!overLimit && (bounds.width <= 0 || bounds.height <= 0)) {
       placedBounds.push(bounds);
       continue;
     }
@@ -1941,11 +2531,13 @@ function thinAnnotations(annotations, specs, measure, plotArea, containerBounds)
     );
     const candidateArea = bounds.width * bounds.height;
     const overBudget = plotAreaSize > 0 && usedArea + candidateArea > coverageBudget;
-    if (overlaps || !fitsWithin(bounds, containment) || overBudget) {
+    if (overLimit || overlaps || !fitsWithin(bounds, containment) || overBudget) {
       const footnoteIndex = footnotes.length + 1;
       footnotes.push({
+        ...entry.resolved.specIndex !== void 0 ? { specIndex: entry.resolved.specIndex } : {},
+        ...entry.resolved.id !== void 0 ? { id: entry.resolved.id } : {},
         index: footnoteIndex,
-        text: entry.resolved.label.text
+        text: entry.spec?.subtitle ? `${entry.resolved.label.text}. ${entry.spec.subtitle}` : entry.resolved.label.text
       });
       entry.resolved.footnoteIndex = footnoteIndex;
     } else {
@@ -1960,8 +2552,62 @@ function fitsWithin(bounds, plotArea) {
   return bounds.x >= plotArea.x && bounds.y >= plotArea.y && bounds.x + bounds.width <= plotArea.x + plotArea.width && bounds.y + bounds.height <= plotArea.y + plotArea.height;
 }
 
+// src/compiler/mark-options.ts
+var APPLIES_TO = {
+  point: ["line", "area", "density"],
+  interpolate: ["line", "area", "density"],
+  orient: ["bar", "histogram"],
+  cornerRadius: ["bar", "rect", "histogram", "waffle"],
+  innerRadius: ["arc"],
+  outerRadius: ["arc"],
+  startAngle: ["arc"],
+  endAngle: ["arc"],
+  centerLabel: ["arc"],
+  binCount: ["histogram"],
+  normalize: ["histogram"],
+  bandwidth: ["density"],
+  cumulative: ["density"],
+  steps: ["density"],
+  trendline: ["point"],
+  dx: ["text"],
+  dy: ["text"],
+  align: ["text"],
+  baseline: ["text"],
+  fontSize: ["text"],
+  style: ["range"],
+  colorByDirection: ["range"],
+  units: ["waffle"],
+  columns: ["waffle"],
+  other: ["waffle"],
+  weekStart: ["calendar"],
+  cellRadius: ["calendar"],
+  shape: ["parliament"],
+  seatRadius: ["parliament"],
+  majorityLine: ["parliament"]
+};
+function collectMarkOptionWarnings(input, path = "") {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return [];
+  const spec = input;
+  const warnings = [];
+  if (spec.mark && typeof spec.mark === "object" && !Array.isArray(spec.mark)) {
+    const mark = spec.mark;
+    for (const [key, allowed] of Object.entries(APPLIES_TO)) {
+      if (mark[key] !== void 0 && !allowed.includes(mark.type)) {
+        warnings.push(
+          `[openchart] ${path}/mark/${key} has no effect on mark "${mark.type}". Remove ${key}, or use a supported mark: ${allowed.join(", ")}.`
+        );
+      }
+    }
+  }
+  if (Array.isArray(spec.layer))
+    spec.layer.forEach((child, i) => {
+      warnings.push(...collectMarkOptionWarnings(child, `${path}/layer/${i}`));
+    });
+  return warnings;
+}
+
 // src/endpoint-labels/compute.ts
-import { estimateTextWidth as estimateTextWidth2, wrapText } from "@opendata-ai/openchart-core";
+import { estimateTextWidth as estimateTextWidth3, wrapText as wrapText2 } from "@opendata-ai/openchart-core";
 
 // src/format/field-format.ts
 import {
@@ -2292,7 +2938,7 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy, endpoint
     const formatted = formatEndpointValue(rawValue, endpointFormatter);
     const labelText = trailingContent ? composeEndpointText(trailingContent, seriesKey, formatted) : seriesKey;
     const value = trailingContent ? "" : formatted;
-    const labelLines = wrapText(
+    const labelLines = wrapText2(
       labelText,
       ENDPOINT_LABEL_FONT_SIZE,
       ENDPOINT_LABEL_FONT_WEIGHT,
@@ -2300,10 +2946,10 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy, endpoint
     );
     let entryWidth = 0;
     for (const line4 of labelLines) {
-      const w = estimateTextWidth2(line4, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+      const w = estimateTextWidth3(line4, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
       if (w > entryWidth) entryWidth = w;
     }
-    const valueWidth = value ? estimateTextWidth2(value, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT) : 0;
+    const valueWidth = value ? estimateTextWidth3(value, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT) : 0;
     if (valueWidth > entryWidth) entryWidth = valueWidth;
     const labelHeight = labelLines.length * labelLineHeight;
     const valueHeight = value ? valueLineHeight : 0;
@@ -2375,7 +3021,7 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy, endpoint
       const formatted = formatEndpointValue(rawValue, endpointFormatter);
       const labelText = leadingContent ? composeEndpointText(leadingContent, seriesKey, formatted) : seriesKey;
       const value = leadingContent ? "" : formatted;
-      const labelLines = wrapText(
+      const labelLines = wrapText2(
         labelText,
         ENDPOINT_LABEL_FONT_SIZE,
         ENDPOINT_LABEL_FONT_WEIGHT,
@@ -2383,10 +3029,10 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy, endpoint
       );
       let entryWidth = 0;
       for (const line4 of labelLines) {
-        const w = estimateTextWidth2(line4, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+        const w = estimateTextWidth3(line4, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
         if (w > entryWidth) entryWidth = w;
       }
-      const valueWidth = value ? estimateTextWidth2(value, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT) : 0;
+      const valueWidth = value ? estimateTextWidth3(value, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT) : 0;
       if (valueWidth > entryWidth) entryWidth = valueWidth;
       const labelHeight = labelLines.length * labelLineHeight;
       const valueHeight = value ? valueLineHeight : 0;
@@ -3035,7 +3681,7 @@ function computeSimpleBars(data, valueField, categoryField, xScale, yScale, band
 
 // src/charts/bar/labels.ts
 import {
-  estimateTextWidth as estimateTextWidth3,
+  estimateTextWidth as estimateTextWidth4,
   getRepresentativeColor as getRepresentativeColor2,
   pickLabelColor,
   resolveCollisions
@@ -3106,7 +3752,7 @@ function computeBarLabels(marks, chartArea, density = "auto", labelFormatter, la
     }
     if (labelPrefix) valuePart = labelPrefix + valuePart;
     if (labelSuffix) valuePart = valuePart + labelSuffix;
-    const textWidth = estimateTextWidth3(valuePart, FONT_SIZE, LABEL_FONT_WEIGHT);
+    const textWidth = estimateTextWidth4(valuePart, FONT_SIZE, LABEL_FONT_WEIGHT);
     const textHeight = FONT_SIZE * 1.2;
     const isStacked2 = mark.stackGroup !== void 0;
     const isInside = mark.width >= MIN_WIDTH_FOR_INSIDE_LABEL;
@@ -4109,7 +4755,7 @@ function applyMarkDefOverrides2(marks, spec, bandwidth) {
 
 // src/charts/column/labels.ts
 import {
-  estimateTextWidth as estimateTextWidth4,
+  estimateTextWidth as estimateTextWidth5,
   getRepresentativeColor as getRepresentativeColor3,
   pickLabelColor as pickLabelColor2,
   resolveCollisions as resolveCollisions2,
@@ -4150,7 +4796,7 @@ function computeColumnLabels(marks, _chartArea, density = "auto", labelFormatter
     const isNegative = Number.isFinite(numericValue) && numericValue < 0;
     if (labelPrefix) valuePart = labelPrefix + valuePart;
     if (labelSuffix) valuePart = valuePart + labelSuffix;
-    const textWidth = estimateTextWidth4(valuePart, FONT_SIZE, LABEL_FONT_WEIGHT2);
+    const textWidth = estimateTextWidth5(valuePart, FONT_SIZE, LABEL_FONT_WEIGHT2);
     const textHeight = FONT_SIZE * 1.2;
     const isStacked2 = mark.stackGroup !== void 0;
     const anchorX = mark.x + mark.width / 2;
@@ -4424,7 +5070,7 @@ function computeLollipopMarks(data, valueField, categoryField, xScale, yScale, b
 
 // src/charts/dot/labels.ts
 import {
-  estimateTextWidth as estimateTextWidth5,
+  estimateTextWidth as estimateTextWidth6,
   getRepresentativeColor as getRepresentativeColor4,
   resolveCollisions as resolveCollisions3
 } from "@opendata-ai/openchart-core";
@@ -4454,7 +5100,7 @@ function computeDotLabels(marks, _chartArea, density = "auto", labelPrefix, labe
       }
     }
     if (labelPrefix) valuePart = labelPrefix + valuePart;
-    const textWidth = estimateTextWidth5(valuePart, LABEL_FONT_SIZE3, LABEL_FONT_WEIGHT3);
+    const textWidth = estimateTextWidth6(valuePart, LABEL_FONT_SIZE3, LABEL_FONT_WEIGHT3);
     const textHeight = LABEL_FONT_SIZE3 * 1.2;
     candidates.push({
       text: valuePart,
@@ -5046,7 +5692,7 @@ function computeAreaMarks(spec, scales, chartArea, theme) {
 // src/charts/line/labels.ts
 import {
   EXTENDED_OFFSET_STRATEGIES,
-  estimateTextWidth as estimateTextWidth6,
+  estimateTextWidth as estimateTextWidth7,
   resolveCollisions as resolveCollisions4
 } from "@opendata-ai/openchart-core";
 var LABEL_FONT_SIZE4 = 11;
@@ -5076,7 +5722,7 @@ function computeLineLabels(marks, strategy, density = "auto", labelOffsets, spec
     const labelText = mark.seriesKey ?? "";
     if (!labelText) continue;
     const lastPoint = mark.points[mark.points.length - 1];
-    const textWidth = estimateTextWidth6(labelText, LABEL_FONT_SIZE4, LABEL_FONT_WEIGHT4);
+    const textWidth = estimateTextWidth7(labelText, LABEL_FONT_SIZE4, LABEL_FONT_WEIGHT4);
     const textHeight = LABEL_FONT_SIZE4 * 1.2;
     candidates.push({
       text: labelText,
@@ -5543,7 +6189,7 @@ function computePieMarks(spec, scales, chartArea, _strategy, isDonut = false, th
 }
 
 // src/charts/pie/labels.ts
-import { estimateTextWidth as estimateTextWidth7, resolveCollisions as resolveCollisions5 } from "@opendata-ai/openchart-core";
+import { estimateTextWidth as estimateTextWidth8, resolveCollisions as resolveCollisions5 } from "@opendata-ai/openchart-core";
 var LABEL_FONT_SIZE5 = 11;
 var LABEL_FONT_WEIGHT5 = 500;
 var LEADER_LINE_OFFSET = 12;
@@ -5571,7 +6217,7 @@ function computePieLabels(marks, _chartArea, density = "auto", _textFill = "#333
     const rawValue = Number(rawValueText);
     const valueText = formatValue3 && Number.isFinite(rawValue) ? formatValue3(rawValue) : percentText;
     const labelText = valueText ? `${sliceName} ${valueText}` : sliceName;
-    const textWidth = estimateTextWidth7(labelText, LABEL_FONT_SIZE5, LABEL_FONT_WEIGHT5);
+    const textWidth = estimateTextWidth8(labelText, LABEL_FONT_SIZE5, LABEL_FONT_WEIGHT5);
     const textHeight = LABEL_FONT_SIZE5 * 1.2;
     const midAngle = (mark.startAngle + mark.endAngle) / 2;
     const labelRadius = mark.outerRadius + LEADER_LINE_OFFSET;
@@ -5896,7 +6542,7 @@ function computeRangeMarks(spec, scales, _chartArea, _strategy, theme) {
 
 // src/charts/range/labels.ts
 import {
-  estimateTextWidth as estimateTextWidth8,
+  estimateTextWidth as estimateTextWidth9,
   getRepresentativeColor as getRepresentativeColor9,
   resolveCollisions as resolveCollisions6
 } from "@opendata-ai/openchart-core";
@@ -5910,7 +6556,7 @@ function formatEndpoint(value, formatter, prefix) {
   return prefix ? prefix + text : text;
 }
 function buildCandidate(mark, text, horizontal, outerSide, index) {
-  const textWidth = estimateTextWidth8(text, LABEL_FONT_SIZE6, LABEL_FONT_WEIGHT6);
+  const textWidth = estimateTextWidth9(text, LABEL_FONT_SIZE6, LABEL_FONT_WEIGHT6);
   const textHeight = LABEL_FONT_SIZE6 * 1.2;
   let anchorX;
   let anchorY;
@@ -6628,10 +7274,11 @@ function registerBuiltinRenderers() {
 registerBuiltinRenderers();
 
 // src/barlist/compile-barlist.ts
+import { mergeThemeConfig } from "@opendata-ai/openchart-core";
 import {
   adaptTheme,
   computeChrome,
-  estimateTextWidth as estimateTextWidth9,
+  estimateTextWidth as estimateTextWidth10,
   resolveTheme
 } from "@opendata-ai/openchart-core";
 
@@ -7299,34 +7946,33 @@ function expandLayerSugar(spec, warnings, inheritedData, parentEncoding) {
 }
 function expandValueFormatSugar(spec, warnings) {
   const type = spec.type;
-  if (type !== "sankey" && type !== "tilemap" && type !== "barlist") return spec;
+  if (type !== "sankey" && type !== "tilemap" && type !== "barlist" && type !== "map") return spec;
   if (typeof spec.valueFormat !== "string") return spec;
   const encoding = spec.encoding;
-  const valueCh = encoding?.value;
+  const channelKey = type === "map" ? "color" : "value";
+  const valueCh = encoding?.[channelKey];
   if (!valueCh || typeof valueCh !== "object") {
-    warnings.push(
-      "[openchart] valueFormat is deprecated; set format on the encoding value channel instead (e.g. encoding.value.format)."
-    );
+    if (type === "tilemap") return spec;
+    warnings.push(`[openchart] valueFormat is deprecated; use encoding.${channelKey}.format.`);
     return spec;
   }
   if (valueCh.format !== void 0) {
     const { valueFormat: _vf, ...rest2 } = spec;
     warnings.push(
-      "[openchart] valueFormat is deprecated; the encoding.value.format field takes precedence and valueFormat was ignored."
+      `[openchart] valueFormat is deprecated; encoding.${channelKey}.format takes precedence and valueFormat was ignored.`
     );
     return rest2;
   }
-  warnings.push(
-    "[openchart] valueFormat is deprecated; set format on the encoding value channel instead (e.g. encoding.value.format)."
-  );
+  warnings.push(`[openchart] valueFormat is deprecated; use encoding.${channelKey}.format.`);
   const { valueFormat, ...rest } = spec;
   return {
     ...rest,
-    encoding: { ...encoding, value: { ...valueCh, format: valueFormat } }
+    encoding: { ...encoding, [channelKey]: { ...valueCh, format: valueFormat } }
   };
 }
-function expandSpecSugar(spec, warnings = []) {
+function expandSpecSugar(spec, warnings = [], markOptionWarnings = true) {
   if (!spec || typeof spec !== "object" || Array.isArray(spec)) return spec;
+  if (markOptionWarnings) warnings.push(...collectMarkOptionWarnings(spec));
   if (Array.isArray(spec.layer) && typeof spec.type !== "string") {
     return expandLayerSugar(spec, warnings);
   }
@@ -7335,16 +7981,35 @@ function expandSpecSugar(spec, warnings = []) {
   }
   return expandChartSugar(spec, warnings);
 }
+var emittedDeprecations = /* @__PURE__ */ new WeakMap();
 var defaultWarnSink = (message) => console.warn(message);
 function emitSpecWarnings(warnings, sink = defaultWarnSink) {
   if (warnings.length === 0) return;
   const seen = /* @__PURE__ */ new Set();
+  const warningSink = sink === defaultWarnSink ? console.warn : sink;
+  let deprecated = emittedDeprecations.get(warningSink);
+  if (!deprecated) {
+    deprecated = /* @__PURE__ */ new Set();
+    emittedDeprecations.set(warningSink, deprecated);
+  }
   for (const warning of warnings) {
+    if (/deprecated|has no effect|removed in v8/i.test(warning)) {
+      if (deprecated.has(warning)) continue;
+      deprecated.add(warning);
+    }
     if (seen.has(warning)) continue;
     seen.add(warning);
     sink(warning);
   }
 }
+function emitThemeWarnings(theme, sink) {
+  if (theme?.chrome && Object.values(theme.chrome).some((value) => typeof value === "string")) {
+    emitSpecWarnings(
+      ["[openchart] theme.chrome string colors are deprecated; use { color } objects."],
+      sink
+    );
+  }
+}
 
 // src/compiler/animation.ts
 import { FLUID_SPRING, springDuration } from "@opendata-ai/openchart-core";
@@ -7661,27 +8326,30 @@ function inferEncodingTypes(encoding, data, warnings) {
   }
   return result;
 }
-function normalizeAnnotations(annotations) {
+function normalizeAnnotations(annotations, warnings) {
   if (!annotations || annotations.length === 0) return [];
   return annotations.map((ann) => {
     switch (ann.type) {
       case "text":
+        if (ann.connector !== null && typeof ann.connector === "object" && ann.connector.type !== "curve" && ann.connector.bend !== void 0) {
+          warnings.push("Annotation connector.bend is ignored unless connector.type is curve.");
+        }
         return {
           ...ann,
           opacity: ann.opacity ?? 1
         };
+      // Omitted ink resolves through theme tokens. Their 8.x defaults preserve
+      // the colors historically stamped here; explicit authored ink stays intact.
       case "range":
         return {
           ...ann,
-          opacity: ann.opacity ?? 0.1,
-          fill: ann.fill ?? "#000000"
+          opacity: ann.opacity ?? 0.1
         };
       case "refline":
         return {
           ...ann,
           style: ann.style ?? "dashed",
           strokeWidth: ann.strokeWidth ?? 1,
-          stroke: ann.stroke ?? "#666666",
           opacity: ann.opacity ?? 0.8
         };
       default:
@@ -7849,10 +8517,11 @@ function normalizeChartSpec(spec, warnings) {
     metrics: spec.metrics,
     seriesSearch: normalizeSeriesSearch(spec, encoding, warnings),
     youDrawIt: normalizeYouDrawIt(spec),
-    annotations: normalizeAnnotations(spec.annotations),
+    annotations: normalizeAnnotations(spec.annotations, warnings),
     labels: normalizeLabels(spec.labels),
     legend: spec.legend,
     endpointLabels: spec.endpointLabels,
+    compactAnnotationLimit: typeof spec.responsive === "object" ? spec.responsive.compactAnnotationLimit : void 0,
     responsive: typeof spec.responsive === "object" ? true : spec.responsive ?? true,
     autoThin: typeof spec.responsive === "object" ? spec.responsive.autoThin ?? true : spec.responsive ?? true,
     theme: spec.theme ?? {},
@@ -7879,16 +8548,15 @@ function normalizeChartSpec(spec, warnings) {
     }
   };
 }
-function normalizeTableDensity(spec, warnings) {
+function normalizeTableDensity(spec) {
   if (spec.density) return spec.density;
   if (spec.compact) {
-    warnings.push('[openchart] table "compact" is deprecated; use density: "condensed" instead.');
     return "condensed";
   }
   return "regular";
 }
-function normalizeTableSpec(spec, warnings) {
-  const density = normalizeTableDensity(spec, warnings);
+function normalizeTableSpec(spec, _warnings) {
+  const density = normalizeTableDensity(spec);
   const totalRow = spec.totalRow === true ? { label: "Total" } : spec.totalRow && typeof spec.totalRow === "object" ? { label: spec.totalRow.label ?? "Total" } : void 0;
   return {
     type: "table",
@@ -7953,7 +8621,7 @@ function normalizeGraphSpec(spec, warnings) {
     nodeOverrides: spec.nodeOverrides,
     seedNode,
     chrome: normalizeChrome(spec.chrome),
-    annotations: normalizeAnnotations(spec.annotations),
+    annotations: normalizeAnnotations(spec.annotations, warnings),
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? "off",
     watermark: spec.watermark ?? true,
@@ -8057,6 +8725,32 @@ function normalizeBarListSpec(spec, _warnings) {
   };
 }
 function normalizeSpec(spec, warnings = []) {
+  const authored = spec;
+  if (authored.darkMode !== void 0)
+    warnings.push(
+      "[openchart] spec darkMode is deprecated and has no effect; use the mount darkMode option."
+    );
+  const themeChrome = authored.theme?.chrome;
+  if (themeChrome && Object.values(themeChrome).some((value) => typeof value === "string"))
+    warnings.push("[openchart] theme.chrome string colors are deprecated; use { color } objects.");
+  if (authored.animation === "legacy" || authored.animation?.preset === "legacy")
+    warnings.push("[openchart] animation legacy is deprecated; omit preset to retain v8 timing.");
+  if (authored.labels?.offsets !== void 0)
+    warnings.push(
+      "[openchart] labels.offsets is deprecated; use endpointLabels. Migration drops manual offsets."
+    );
+  if (authored.type === "table" && "compact" in authored)
+    warnings.push(
+      '[openchart] table "compact" is deprecated; use density: "condensed" (true) or "regular" (false).'
+    );
+  const annotations = authored.annotations;
+  if (Array.isArray(annotations)) {
+    const ids = annotations.map((a) => a.id).filter((id) => id !== void 0);
+    if (ids.length !== annotations.length || new Set(ids).size !== ids.length)
+      warnings.push(
+        "[openchart] Missing or duplicate annotation IDs use revision-local source indices; provide unique IDs for durable identity."
+      );
+  }
   if (isLayerSpec(spec)) {
     const leaves = flattenLayers(spec);
     if (leaves.length === 0) {
@@ -8991,8 +9685,8 @@ function validateGraphSpec(spec, errors) {
   const nodeIds = /* @__PURE__ */ new Set();
   const nodes = spec.nodes;
   for (let i = 0; i < nodes.length; i++) {
-    const node = nodes[i];
-    if (!node || typeof node !== "object") {
+    const node2 = nodes[i];
+    if (!node2 || typeof node2 !== "object") {
       errors.push({
         message: `Spec error: nodes[${i}] must be an object`,
         path: `nodes[${i}]`,
@@ -9001,7 +9695,7 @@ function validateGraphSpec(spec, errors) {
       });
       continue;
     }
-    if (typeof node.id !== "string" || node.id === "") {
+    if (typeof node2.id !== "string" || node2.id === "") {
       errors.push({
         message: `Spec error: nodes[${i}] must have a non-empty string "id" field`,
         path: `nodes[${i}].id`,
@@ -9009,7 +9703,7 @@ function validateGraphSpec(spec, errors) {
         suggestion: 'Add a string id to the node, e.g. { id: "node1" }'
       });
     } else {
-      nodeIds.add(node.id);
+      nodeIds.add(node2.id);
     }
   }
   if (spec.seedNode !== void 0) {
@@ -9096,9 +9790,9 @@ function validateGraphSpec(spec, errors) {
   if (spec.encoding && typeof spec.encoding === "object") {
     const encoding = spec.encoding;
     const nodeFields = /* @__PURE__ */ new Set();
-    for (const node of nodes) {
-      if (node && typeof node === "object") {
-        for (const key of Object.keys(node)) nodeFields.add(key);
+    for (const node2 of nodes) {
+      if (node2 && typeof node2 === "object") {
+        for (const key of Object.keys(node2)) nodeFields.add(key);
       }
     }
     const edgeFields = /* @__PURE__ */ new Set();
@@ -9882,7 +10576,55 @@ function validateFieldMetadata(obj, errors) {
     }
   }
 }
-function validateSpec(spec) {
+function validateAnnotationLayout(spec, errors, prefix = "") {
+  const responsive = spec.responsive;
+  const limit = responsive && typeof responsive === "object" ? responsive.compactAnnotationLimit : void 0;
+  if (limit != null && (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0)) {
+    errors.push({
+      code: "INVALID_VALUE",
+      path: `${prefix}responsive.compactAnnotationLimit`,
+      message: "compactAnnotationLimit must be a nonnegative integer or null",
+      suggestion: "Use null for unlimited inline annotations."
+    });
+  }
+  if (Array.isArray(spec.annotations)) {
+    for (const [index, annotation] of spec.annotations.entries()) {
+      for (const field of ["maxWidth", "subtitleFontSize"]) {
+        const value = annotation?.[field];
+        if (value === void 0 || field === "maxWidth" && value === null) continue;
+        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+          errors.push({
+            code: "INVALID_VALUE",
+            path: `${prefix}annotations[${index}].${field}`,
+            message: `${field} must be a positive finite number`,
+            suggestion: field === "maxWidth" ? "Use null for unlimited width." : "Omit subtitleFontSize to use the default ratio."
+          });
+      }
+      if (annotation?.labelPlacement !== void 0 && !["auto", "start", "end", "outside"].includes(annotation.labelPlacement))
+        errors.push({
+          code: "INVALID_VALUE",
+          path: `${prefix}annotations[${index}].labelPlacement`,
+          message: "Unknown reference label placement",
+          suggestion: "Use auto, start, end or outside."
+        });
+      const bend = annotation?.connector?.bend;
+      if (bend !== void 0 && (typeof bend !== "number" || !Number.isFinite(bend) || bend < -1 || bend > 1)) {
+        errors.push({
+          code: "INVALID_VALUE",
+          path: `${prefix}annotations[${index}].connector.bend`,
+          message: "Connector bend must be a finite number between -1 and 1",
+          suggestion: "Omit bend for the automatic curve, or use a number in [-1, 1]."
+        });
+      }
+    }
+  }
+  if (Array.isArray(spec.layer))
+    for (const [index, child] of spec.layer.entries()) {
+      if (child && typeof child === "object" && !Array.isArray(child))
+        validateAnnotationLayout(child, errors, `${prefix}layer[${index}].`);
+    }
+}
+function validateSpecShape(spec) {
   const errors = [];
   if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
     return {
@@ -9898,6 +10640,7 @@ function validateSpec(spec) {
     };
   }
   const obj = spec;
+  validateAnnotationLayout(obj, errors);
   validateFieldMetadata(obj, errors);
   if (obj.chrome !== void 0) {
     const chrome = obj.chrome;
@@ -10027,16 +10770,21 @@ function validateSpec(spec) {
     normalized: spec
   };
 }
+function validateSpec(spec) {
+  const result = validateSpecShape(spec);
+  const warnings = collectMarkOptionWarnings(spec);
+  return warnings.length ? { ...result, warnings } : result;
+}
 
 // src/compiler/index.ts
-function compile(spec) {
+function compile(spec, options) {
   const validation = validateSpec(spec);
   if (!validation.valid || !validation.normalized) {
     const errorMessages = validation.errors.map((e) => e.message).join("\n");
     throw new Error(`Invalid spec:
 ${errorMessages}`);
   }
-  const warnings = [];
+  const warnings = options?.markOptionWarnings === false ? [] : [...validation.warnings ?? []];
   const normalized = normalizeSpec(validation.normalized, warnings);
   return { spec: normalized, warnings };
 }
@@ -10068,9 +10816,6 @@ function bottomMargin(bottomHeight, padding, xAxisHeight) {
 }
 var INLINE_TICK_OVERHANG_PAD = 6;
 function resolveChromeLayout(spec, options) {
-  const encoding = spec?.encoding;
-  const isFaceted = !!(encoding?.facet || encoding?.row || encoding?.column);
-  if (isFaceted) return "subtract";
   return spec?.chromeLayout ?? options?.chromeLayout ?? "subtract";
 }
 
@@ -10099,7 +10844,8 @@ function compileBarList(spec, options) {
   const barlistSpec = normalized;
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? barlistSpec.watermark : options.watermark ?? true;
-  const mergedThemeConfig = options.theme ? { ...barlistSpec.theme, ...options.theme } : barlistSpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig(barlistSpec.theme, options.theme);
   const lightTheme = resolveTheme(mergedThemeConfig);
   let theme = lightTheme;
   if (options.darkMode) {
@@ -10168,7 +10914,7 @@ function compileBarList(spec, options) {
     values: validRows.map((r) => r[valueField])
   });
   const measureText = options.measureText ?? ((text, fontSize) => ({
-    width: estimateTextWidth9(text, fontSize),
+    width: estimateTextWidth10(text, fontSize),
     height: fontSize
   }));
   const perRowLabelWidths = /* @__PURE__ */ new Map();
@@ -10376,7 +11122,7 @@ function emptyLayout2(chrome, theme, options, watermark) {
     height: options.height,
     watermark,
     animation: void 0,
-    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth9(text, fontSize), height: fontSize }))
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth10(text, fontSize), height: fontSize }))
   };
 }
 
@@ -10540,7 +11286,7 @@ import {
 import {
   computeFieldFormatContext as computeFieldFormatContext2,
   defaultNumberFormatter as defaultNumberFormatter5,
-  estimateTextWidth as estimateTextWidth10,
+  estimateTextWidth as estimateTextWidth11,
   resolveNumberFormatter as resolveNumberFormatter2,
   resolveSchemeName as resolveSchemeName3
 } from "@opendata-ai/openchart-core";
@@ -10733,7 +11479,7 @@ function computeContinuousLegendContentForChannel(values, channel, theme, availa
     const rowEnds = [];
     const rowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
     for (const tick of ticks2) {
-      const width = estimateTextWidth10(
+      const width = estimateTextWidth11(
         tick.label,
         theme.fonts.sizes.small,
         theme.fonts.weights.normal
@@ -10988,8 +11734,12 @@ import {
   axisTitleOffset as axisTitleOffset3,
   BREAKPOINT_COMPACT_MAX as BREAKPOINT_COMPACT_MAX2,
   computeFieldFormatContext as computeFieldFormatContext5,
+  computeNoteBandHeight,
   defaultNumberFormatter as defaultNumberFormatter7,
-  estimateTextWidth as estimateTextWidth18,
+  estimateTextWidth as estimateTextWidth19,
+  getBreakpoint,
+  getHeightClass as getHeightClass2,
+  getLayoutStrategy,
   resolveNumberFormatter as resolveNumberFormatter5,
   resolveTheme as resolveTheme2,
   TICK_LABEL_OFFSET
@@ -11007,7 +11757,7 @@ import {
   computeFieldFormatContext as computeFieldFormatContext4,
   computeXAxisExtentFromLabels as computeXAxisExtentFromLabels2,
   defaultNumberFormatter as defaultNumberFormatter6,
-  estimateTextWidth as estimateTextWidth17,
+  estimateTextWidth as estimateTextWidth18,
   getHeightClass,
   HPAD_COMPACT_FRACTION,
   HPAD_COMPACT_MIN,
@@ -11024,7 +11774,7 @@ import {
 } from "@opendata-ai/openchart-core";
 
 // src/endpoint-labels/predict.ts
-import { estimateTextWidth as estimateTextWidth11, wrapText as wrapText2 } from "@opendata-ai/openchart-core";
+import { estimateTextWidth as estimateTextWidth12, wrapText as wrapText3 } from "@opendata-ai/openchart-core";
 function predictEndpointLabelsWidth(spec, _theme) {
   if (spec.endpointLabels === false) return 0;
   if (spec.markType !== "line" && spec.markType !== "area") return 0;
@@ -11067,14 +11817,14 @@ function predictEndpointLabelsWidth(spec, _theme) {
     let maxWidth = 0;
     for (const name of seriesNames) {
       const text = content ? composeEndpointText(content, name, sample) : name;
-      const lines = wrapText2(text, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT, wrapWidth);
+      const lines = wrapText3(text, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT, wrapWidth);
       for (const line4 of lines) {
-        const w = estimateTextWidth11(line4, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+        const w = estimateTextWidth12(line4, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
         if (w > maxWidth) maxWidth = w;
       }
     }
     if (!content && sample) {
-      const w = estimateTextWidth11(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
+      const w = estimateTextWidth12(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
       if (w > maxWidth) maxWidth = w;
     }
     return maxWidth;
@@ -11091,7 +11841,7 @@ function isEndsBoth(spec) {
 }
 
 // src/legend/compute.ts
-import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH as COMPACT_WIDTH2, estimateTextWidth as estimateTextWidth13 } from "@opendata-ai/openchart-core";
+import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH as COMPACT_WIDTH2, estimateTextWidth as estimateTextWidth14 } from "@opendata-ai/openchart-core";
 
 // src/layout/scales.ts
 import { computeFieldFormatContext as computeFieldFormatContext3 } from "@opendata-ai/openchart-core";
@@ -11679,7 +12429,7 @@ function computeScales(spec, chartArea, data) {
 }
 
 // src/legend/wrap.ts
-import { COMPACT_WIDTH, estimateTextWidth as estimateTextWidth12 } from "@opendata-ai/openchart-core";
+import { COMPACT_WIDTH, estimateTextWidth as estimateTextWidth13 } from "@opendata-ai/openchart-core";
 var SWATCH_SIZE = 12;
 var SWATCH_GAP = 6;
 var ENTRY_GAP = 16;
@@ -11693,7 +12443,7 @@ function measureLegendWrap(entries, maxWidth, labelStyle, maxRows, entryGap = EN
   if (entries.length === 0) {
     return { rowCount: 0, fittingCount: 0, rowWidths: [], placements: [] };
   }
-  const measureWidth = measure ?? estimateTextWidth12;
+  const measureWidth = measure ?? estimateTextWidth13;
   let rowCount = 1;
   let rowWidth = 0;
   const rowWidths = [];
@@ -11839,7 +12589,7 @@ function emptyContent(position, theme) {
   };
 }
 function computeLegendContent(spec, strategy, theme, availableWidth, availableHeight, watermark = true, measure, endpointLabelsDemoted) {
-  const measureWidth = measure ?? estimateTextWidth13;
+  const measureWidth = measure ?? estimateTextWidth14;
   const sparklineHidden = spec.display === "sparkline" && !spec.userExplicit.legend;
   if (sparklineHidden || spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return emptyContent("top", theme);
@@ -11851,7 +12601,7 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
     if (!continuous) {
       return emptyContent(continuousPosition, theme);
     }
-    const labelStyle2 = {
+    const labelStyle = {
       fontFamily: theme.fonts.family,
       fontSize: theme.fonts.sizes.small,
       fontWeight: theme.fonts.weights.normal,
@@ -11859,13 +12609,13 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
       lineHeight: 1.3,
       fontVariant: "tabular-nums"
     };
-    const labelRowHeight = Math.ceil(labelStyle2.fontSize * labelStyle2.lineHeight);
+    const labelRowHeight = Math.ceil(labelStyle.fontSize * labelStyle.lineHeight);
     const height = compact ? Math.max(continuous.barHeight, labelRowHeight) : continuous.barHeight + CONTINUOUS_LABEL_GAP + labelRowHeight * (continuous.labelRows ?? 1);
     const blockWidth = continuous.blockWidth ?? continuous.barWidth;
     return {
       entries: [],
       position: continuousPosition,
-      labelStyle: labelStyle2,
+      labelStyle,
       rowCount: 1,
       totalWidth: blockWidth,
       height,
@@ -11903,6 +12653,18 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
   if (spec.markType === "arc" && everySliceLabeled && uncrowded && !spec.userExplicit?.legend) {
     entries = [];
   }
+  return measureCategoricalLegendContent(
+    entries,
+    spec.legend,
+    strategy,
+    theme,
+    availableWidth,
+    availableHeight,
+    watermark,
+    measureWidth
+  );
+}
+function measureCategoricalLegendContent(entries, legend, strategy, theme, availableWidth, availableHeight, watermark = true, measureWidth = estimateTextWidth14) {
   const labelStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,
@@ -11913,12 +12675,12 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
     // of entries from shimmying.
     fontVariant: "tabular-nums"
   };
-  const specPosition = spec.legend?.position === "top-left" ? "top" : spec.legend?.position;
+  const specPosition = legend?.position === "top-left" ? "top" : legend?.position;
   const resolvedPosition = specPosition ?? (strategy.legendPosition === "right" ? "right" : "top");
   if (entries.length === 0) {
     return emptyContent(resolvedPosition, theme);
   }
-  const offset = spec.legend?.offset;
+  const offset = legend?.offset;
   if (resolvedPosition === "right" || resolvedPosition === "bottom-right") {
     const maxLabelWidth = Math.max(
       ...entries.map((e) => measureWidth(e.label, labelStyle.fontSize, labelStyle.fontWeight))
@@ -11934,7 +12696,7 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
       1,
       Math.floor((maxLegendHeight - LEGEND_PADDING * 2) / (entryHeight + 4))
     );
-    const maxEntries = spec.legend?.symbolLimit != null ? Math.max(1, spec.legend.symbolLimit) : maxFromSpace;
+    const maxEntries = legend?.symbolLimit != null ? Math.max(1, legend.symbolLimit) : maxFromSpace;
     if (entries.length > maxEntries) {
       entries = truncateEntries(entries, maxEntries);
     }
@@ -11975,13 +12737,13 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
   const effectivePadding = isCompact ? 2 : LEGEND_PADDING;
   const effectiveEntryGap = isCompact ? ENTRY_GAP_COMPACT : ENTRY_GAP;
   const contentWidth = availableWidth - effectivePadding * 2 - (reserveBrand ? BRAND_RESERVE_WIDTH : 0);
-  if (spec.legend?.symbolLimit != null) {
-    const limit = Math.max(1, spec.legend.symbolLimit);
+  if (legend?.symbolLimit != null) {
+    const limit = Math.max(1, legend.symbolLimit);
     if (limit < entries.length) {
       entries = truncateEntries(entries, limit);
     }
   }
-  const maxRows = spec.legend?.maxRows != null ? Math.max(1, spec.legend.maxRows) : spec.legend?.columns != null ? Math.ceil(entries.length / spec.legend.columns) : TOP_LEGEND_MAX_ROWS;
+  const maxRows = legend?.maxRows != null ? Math.max(1, legend.maxRows) : legend?.columns != null ? Math.ceil(entries.length / legend.columns) : TOP_LEGEND_MAX_ROWS;
   const { fittingCount } = measureLegendWrap(
     entries,
     contentWidth,
@@ -12117,7 +12879,7 @@ function placeLegend(content, chartArea, containerWidth, _theme, xAxisHeight, ax
 import {
   abbreviateNumber,
   buildD3Formatter,
-  estimateTextWidth as estimateTextWidth14,
+  estimateTextWidth as estimateTextWidth15,
   formatNumber as formatNumber3
 } from "@opendata-ai/openchart-core";
 import { scaleLinear as scaleLinear3, scaleSqrt as scaleSqrt3 } from "d3-scale";
@@ -12233,11 +12995,11 @@ function computeSizeLegendContent(sizeEncoding, data, theme, options) {
     };
   });
   const widestLabel = Math.max(
-    ...circles.map((c) => estimateTextWidth14(c.label, fontSize, theme.fonts.weights.normal))
+    ...circles.map((c) => estimateTextWidth15(c.label, fontSize, theme.fonts.weights.normal))
   );
   const lastLabelBottom = (circles[circles.length - 1]?.labelY ?? 0) + fontSize * 0.5;
   const circleBlockWidth = maxRadius * 2 + LABEL_GAP + widestLabel;
-  const titleWidth = title ? estimateTextWidth14(title, fontSize, theme.fonts.weights.medium) : 0;
+  const titleWidth = title ? estimateTextWidth15(title, fontSize, theme.fonts.weights.medium) : 0;
   return {
     circles,
     width: Math.max(circleBlockWidth, titleWidth),
@@ -12281,7 +13043,7 @@ function placeSizeLegend(content, chartArea, theme, colorLegend) {
 import {
   axisTitleOffset,
   computeXAxisExtentFromLabels,
-  estimateTextWidth as estimateTextWidth16,
+  estimateTextWidth as estimateTextWidth17,
   truncateRotatedLabel,
   X_AXIS_TITLE_BAND,
   X_AXIS_TITLE_BAND_ROTATED
@@ -12326,11 +13088,11 @@ function bandLabelStride(maxLabelWidth, angleDeg, fontSize, spacing) {
 }
 
 // src/layout/axes/thinning.ts
-import { estimateTextWidth as estimateTextWidth15 } from "@opendata-ai/openchart-core";
+import { estimateTextWidth as estimateTextWidth16 } from "@opendata-ai/openchart-core";
 var MIN_TICK_GAP_FACTOR = 0.5;
 var MIN_TICK_COUNT = 2;
 function measureLabel(text, fontSize, fontWeight, measureText) {
-  return measureText ? measureText(text, fontSize, fontWeight).width : estimateTextWidth15(text, fontSize, fontWeight);
+  return measureText ? measureText(text, fontSize, fontWeight).width : estimateTextWidth16(text, fontSize, fontWeight);
 }
 function ticksOverlap(ticks, fontSize, fontWeight, measureText, orientation = "horizontal") {
   if (ticks.length < 2) return false;
@@ -12985,7 +13747,7 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
     const isRight = result.y.orient === "right";
     if (isRight) {
       const maxTickLabelWidth = result.y.ticks.reduce((max4, t) => {
-        const w = estimateTextWidth16(
+        const w = estimateTextWidth17(
           t.label,
           result.y.tickLabelStyle.fontSize,
           result.y.tickLabelStyle.fontWeight ?? 400
@@ -13000,7 +13762,7 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
       };
     } else {
       const maxTickLabelWidth = result.y.ticks.reduce((max4, t) => {
-        const w = estimateTextWidth16(
+        const w = estimateTextWidth17(
           t.label,
           result.y.tickLabelStyle.fontSize,
           result.y.tickLabelStyle.fontWeight ?? 400
@@ -13028,7 +13790,7 @@ function createMeasureFn(measureText) {
   if (measureText) {
     return (text, fontSize, fontWeight) => measureText(text, fontSize, fontWeight).width;
   }
-  return estimateTextWidth17;
+  return estimateTextWidth18;
 }
 function sampleLabelFromContext(maxAbsVal, yAxisFormat, ctx) {
   if (yAxisFormat) {
@@ -13480,7 +14242,7 @@ function estimateYAxisLabelWidth(data, encoding, baseFontSize, measure) {
   const yEnc = encoding.y;
   const yField = yEnc.field;
   if (!yField) return 40;
-  const m = measure ?? estimateTextWidth18;
+  const m = measure ?? estimateTextWidth19;
   const yType = yEnc.type;
   if (yType === "nominal" || yType === "ordinal") {
     let maxWidth = 0;
@@ -13563,10 +14325,77 @@ function compileLayerIndependent(leaves, layerSpec, options, compileChart2) {
     leaf1WithUnionX = withYDomain(leaf1WithUnionX, aligned.domain1);
   }
   const primary0 = buildPrimarySpec([leaf0WithUnionX], layerSpec);
-  const layout0 = compileChart2(primary0, optionsWithReserve);
+  let layout0 = compileChart2(primary0, optionsWithReserve);
   const primary1 = buildPrimarySpec([leaf1WithUnionX], layerSpec);
   primary1.annotations = [];
-  const layout1 = compileChart2(primary1, optionsWithReserve);
+  let layout1 = compileChart2(primary1, optionsWithReserve);
+  const columns = [layout0.endpointLabels, layout1.endpointLabels].filter(
+    (column) => !!column
+  );
+  let leadingColumnX;
+  if (columns.length) {
+    const pad = layout0.theme.spacing.padding;
+    const leadingWidth = Math.max(0, ...columns.map((column) => column.leadingBounds?.width ?? 0));
+    const leftAxisReserve = Math.max(
+      0,
+      layout0.area.x - pad - (layout0.endpointLabels?.leadingBounds ? layout0.endpointLabels.leadingBounds.width + 16 : 0)
+    );
+    const x = Math.max(
+      layout0.area.x,
+      layout1.area.x,
+      leadingWidth ? pad + leadingWidth + ENDPOINT_COLUMN_GAP + leftAxisReserve : 0
+    );
+    leadingColumnX = leadingWidth ? pad : void 0;
+    const y = Math.max(layout0.area.y, layout1.area.y);
+    const endpointWidth = Math.max(...columns.map((column) => column.bounds.width));
+    const rightLegends = [...layout0.legends, ...layout1.legends].filter(isRightLegend);
+    const legendReserve = rightLegends.length ? Math.max(...rightLegends.map((legend) => legend.bounds.width)) + 8 : 0;
+    const referenceReserve = referenceLabelReserve(
+      primary0.annotations ?? [],
+      options.width,
+      options.measureText ? (text, font) => options.measureText(text, font.fontSize, font.fontWeight).width : heuristicMeasure
+    );
+    const right = options.width - pad - rightReserve - ENDPOINT_COLUMN_GAP - endpointWidth - legendReserve - referenceReserve.right;
+    const grow = (primary0.chromeLayout ?? options.chromeLayout) === "grow";
+    const bottom = grow ? layout0.area.y + layout0.area.height : Math.min(layout0.area.y + layout0.area.height, layout1.area.y + layout1.area.height);
+    const area3 = {
+      ...options.frozenChartArea ?? {
+        x,
+        y,
+        width: Math.max(1, right - x),
+        height: Math.max(1, bottom - y)
+      }
+    };
+    let reserve = noteReserve(layout0);
+    for (let pass = 0; pass <= (primary0.annotations?.length ?? 0) + 1; pass++) {
+      const alignedOptions = {
+        ...optionsWithReserve,
+        frozenChartArea: area3,
+        footnoteReserve: reserve
+      };
+      layout0 = compileChart2(primary0, alignedOptions);
+      layout1 = compileChart2(primary1, alignedOptions);
+      const nextReserve = noteReserve(layout0);
+      if (nextReserve <= reserve) break;
+      const delta = nextReserve - reserve;
+      reserve = nextReserve;
+      if (grow) continue;
+      if (options.frozenChartArea) break;
+      area3.height = Math.max(1, area3.height - delta);
+    }
+    const legendShift = rightReserve + ENDPOINT_COLUMN_GAP + endpointWidth;
+    const localColumnReserve = (layout) => layout.endpointLabels?.entries.length ? ENDPOINT_COLUMN_GAP + layout.endpointLabels.bounds.width : 0;
+    layout0 = moveRightLegends(layout0, legendShift - localColumnReserve(layout0));
+    layout1 = moveRightLegends(layout1, legendShift - localColumnReserve(layout1));
+  }
+  if (!columns.length && noteReserve(layout0) > 0) {
+    const reserve = noteReserve(layout0);
+    layout1 = compileChart2(primary1, {
+      ...optionsWithReserve,
+      frozenChartArea: layout0.area,
+      footnoteReserve: reserve
+    });
+  }
   const y2Axis = layout1.axes.y ? {
     ...layout1.axes.y,
     orient: "right",
@@ -13658,6 +14487,43 @@ function compileLayerIndependent(leaves, layerSpec, options, compileChart2) {
     }
     return tagged;
   });
+  const endpointColumns = [layout0, layout1].flatMap((layout, index) => {
+    const column = layout.endpointLabels;
+    if (!column) return [];
+    const sourceMarks = index === 0 ? adjustedMarks0 : taggedMarks1;
+    const remap = (entry, leading = false) => {
+      const line4 = sourceMarks.find(
+        (mark) => mark.type === "line" && mark.seriesKey === entry.seriesKey
+      );
+      if (!entry.marker || line4?.type !== "line") return entry;
+      const points = line4.dataPoints?.length ? line4.dataPoints : line4.points;
+      const point = leading ? points[0] : points.at(-1);
+      if (!point) return entry;
+      return {
+        ...entry,
+        marker: {
+          ...entry.marker,
+          dataX: point.x,
+          x: point.x + (leading ? -1 : 1) * entry.marker.radius
+        }
+      };
+    };
+    const endpointConfig = (index === 0 ? primary0 : primary1).endpointLabels;
+    return [
+      {
+        ...column,
+        leadersEnabled: typeof endpointConfig === "object" && endpointConfig.showLeader === true,
+        entries: column.entries.map((entry) => remap(entry)),
+        leading: column.leading?.map((entry) => remap(entry, true))
+      }
+    ];
+  });
+  const endpointLabels = mergeEndpointColumns(
+    endpointColumns,
+    layout0.area,
+    rightReserve,
+    leadingColumnX
+  );
   const seenLabels = /* @__PURE__ */ new Set();
   const l0Legend = layout0.legend;
   const l1Legend = layout1.legend;
@@ -13681,12 +14547,43 @@ function compileLayerIndependent(leaves, layerSpec, options, compileChart2) {
   for (const layer of layers) {
     appendLayerMarks(layer.layout, layer.leafIndex, marks, mergedTooltips, layer.sourceMarks);
   }
-  const mergedLegend = {
+  let mergedLegend = {
     ...layout0.legend,
     ..."entries" in l0Legend ? { entries: mergedLegendEntries } : {}
   };
+  if (endpointLabels) {
+    const owner = l0Legend.bounds.width > 0 ? layout0 : layout1;
+    if (isRightLegend(owner.legend) && "entries" in owner.legend) {
+      const ownerSpec = owner === layout0 ? primary0 : primary1;
+      const normalized = normalizeSpec(
+        expandSpecSugar(ownerSpec)
+      );
+      const content = measureCategoricalLegendContent(
+        mergedLegendEntries,
+        normalized.legend,
+        getLayoutStrategy(getBreakpoint(options.width), getHeightClass2(options.height)),
+        owner.theme,
+        options.width,
+        layout0.area.height,
+        owner.watermark,
+        measureFn
+      );
+      mergedLegend = placeLegend(
+        content,
+        {
+          ...layout0.area,
+          width: layout0.area.width + rightReserve + ENDPOINT_COLUMN_GAP + endpointLabels.bounds.width
+        },
+        options.width,
+        owner.theme,
+        0
+        // Right legends do not depend on the x-axis extent.
+      );
+    }
+  }
   return {
     ...layout0,
+    ...endpointLabels ? { endpointLabels } : {},
     axes: {
       x: layout0.axes.x,
       y: layout0.axes.y,
@@ -13700,6 +14597,92 @@ function compileLayerIndependent(leaves, layerSpec, options, compileChart2) {
     tooltipDescriptors: mergedTooltips
   };
 }
+function noteReserve(layout) {
+  return layout.chrome.noteBandHeight ?? computeNoteBandHeight(
+    annotationNoteLineCount(layout.chrome.footnotes ?? []) + (layout.chrome.seriesSummary?.reduce((count, entry) => count + entry.lines.length, 0) ?? 0),
+    layout.theme
+  );
+}
+function isRightLegend(legend) {
+  return (legend.position === "right" || legend.position === "bottom-right") && legend.bounds.width > 0;
+}
+function moveRightLegends(layout, dx) {
+  const move = (legend) => {
+    if (!isRightLegend(legend)) return legend;
+    const shifted = { ...legend, bounds: { ...legend.bounds, x: legend.bounds.x + dx } };
+    if ("entryPositions" in legend)
+      return {
+        ...shifted,
+        entryPositions: legend.entryPositions?.map((position) => ({
+          ...position,
+          x: position.x + dx,
+          labelX: position.labelX + dx
+        }))
+      };
+    if (legend.type === "continuous")
+      return {
+        ...shifted,
+        bar: { ...legend.bar, x: legend.bar.x + dx },
+        bins: legend.bins.map((bin) => ({ ...bin, x: bin.x + dx })),
+        ticks: legend.ticks.map((tick) => ({ ...tick, x: tick.x + dx }))
+      };
+    return shifted;
+  };
+  return { ...layout, legend: move(layout.legend), legends: layout.legends.map(move) };
+}
+function mergeEndpointColumns(columns, area3, rightReserve, leadingColumnX) {
+  if (!columns.length) return void 0;
+  const { leadersEnabled: _leadersEnabled, ...first } = columns[0];
+  const sweep = (entries) => {
+    const size = first.labelStyle.fontSize;
+    const tops = bidirectionalSweep(
+      entries.map((entry, index) => ({
+        naturalTop: entry.dataY - size / 2,
+        height: entry.labelLines.length * size * (first.labelStyle.lineHeight ?? 1.25) + (entry.value ? first.valueGap + first.valueStyle.fontSize * (first.valueStyle.lineHeight ?? 1.25) : 0) + ENDPOINT_ENTRY_GAP,
+        index
+      })),
+      area3.y,
+      area3.y + area3.height
+    );
+    return entries.map(({ leadersEnabled, ...entry }, index) => ({
+      ...entry,
+      labelY: tops[index],
+      showLeader: leadersEnabled && Math.abs(tops[index] + size / 2 - entry.dataY) > ENDPOINT_LEADER_THRESHOLD
+    }));
+  };
+  const leadingColumns = columns.filter((column) => column.leadingBounds);
+  const leadingWidth = Math.max(0, ...leadingColumns.map((column) => column.leadingBounds.width));
+  return {
+    ...first,
+    entries: sweep(
+      columns.flatMap(
+        (column) => column.entries.map((entry) => ({ ...entry, leadersEnabled: column.leadersEnabled }))
+      )
+    ),
+    bounds: {
+      x: area3.x + area3.width + rightReserve + ENDPOINT_COLUMN_GAP,
+      y: area3.y,
+      width: Math.max(...columns.map((column) => column.bounds.width)),
+      height: area3.height
+    },
+    ...leadingColumns.length ? {
+      leading: sweep(
+        leadingColumns.flatMap(
+          (column) => (column.leading ?? []).map((entry) => ({
+            ...entry,
+            leadersEnabled: column.leadersEnabled
+          }))
+        )
+      ),
+      leadingBounds: {
+        x: leadingColumnX ?? area3.x - ENDPOINT_COLUMN_GAP - leadingWidth,
+        y: area3.y,
+        width: leadingWidth,
+        height: area3.height
+      }
+    } : {}
+  };
+}
 function withXDomain(leaf, domain) {
   if (!leaf.encoding?.x) return leaf;
   return {
@@ -14168,11 +15151,12 @@ import {
   buildD3Formatter as buildD3Formatter2,
   CATEGORICAL_PALETTE as CATEGORICAL_PALETTE2,
   computeChrome as computeChrome3,
-  estimateTextWidth as estimateTextWidth19,
+  estimateTextWidth as estimateTextWidth20,
   formatNumber as formatNumber4,
-  getBreakpoint,
+  getBreakpoint as getBreakpoint2,
   HPAD_COMPACT_FRACTION as HPAD_COMPACT_FRACTION2,
   HPAD_COMPACT_MIN as HPAD_COMPACT_MIN2,
+  mergeThemeConfig as mergeThemeConfig2,
   resolveTheme as resolveTheme3
 } from "@opendata-ai/openchart-core";
 import { geoArea, geoPath } from "d3-geo";
@@ -14412,10 +15396,10 @@ function categoricalLegendLabelStyle(theme) {
   };
 }
 function categoricalEntryWidth(label, labelStyle) {
-  return CATEGORICAL_SWATCH_SIZE + CATEGORICAL_SWATCH_GAP + estimateTextWidth19(label, labelStyle.fontSize, labelStyle.fontWeight) + CATEGORICAL_ENTRY_GAP;
+  return CATEGORICAL_SWATCH_SIZE + CATEGORICAL_SWATCH_GAP + estimateTextWidth20(label, labelStyle.fontSize, labelStyle.fontWeight) + CATEGORICAL_ENTRY_GAP;
 }
 function noDataBlockWidth(labelStyle) {
-  return CATEGORICAL_SWATCH_SIZE + NO_DATA_LABEL_GAP + estimateTextWidth19("No data", labelStyle.fontSize, labelStyle.fontWeight);
+  return CATEGORICAL_SWATCH_SIZE + NO_DATA_LABEL_GAP + estimateTextWidth20("No data", labelStyle.fontSize, labelStyle.fontWeight);
 }
 function wrapCategoricalEntries(widths, legendWidth) {
   const placed = [];
@@ -14490,13 +15474,15 @@ function compileGeoMap(spec, options) {
   const topology = validateGeoFeatures(mapSpec.geo);
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? mapSpec.watermark : options.watermark ?? true;
-  const mergedThemeConfig = options.theme ? { ...mapSpec.theme, ...options.theme } : mapSpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig2(mapSpec.theme, options.theme);
   const lightTheme = resolveTheme3(mergedThemeConfig);
   let theme = lightTheme;
   if (options.darkMode) {
     theme = adaptTheme2(theme);
   }
   const isDarkMode = options.darkMode;
+  const padding = getBreakpoint2(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN2, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION2)) : theme.spacing.padding;
   const chrome = computeChrome3(
     {
       title: mapSpec.chrome.title,
@@ -14509,10 +15495,9 @@ function compileGeoMap(spec, options) {
     options.width,
     options.measureText,
     "full",
-    void 0,
+    padding,
     watermark
   );
-  const padding = getBreakpoint(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN2, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION2)) : theme.spacing.padding;
   const chromeLayout = resolveChromeLayout(
     spec,
     options
@@ -14728,7 +15713,7 @@ function compileGeoMap(spec, options) {
       const labelY = bar.y + bar.height + CONTINUOUS_LABEL_GAP + labelStyle.fontSize;
       const hasUnmatched = featureMarks.some((m) => m.noData);
       const noDataX = bar.x + bar.width + NO_DATA_SWATCH_GAP;
-      const noDataLabelWidth = estimateTextWidth19(
+      const noDataLabelWidth = estimateTextWidth20(
         "No data",
         labelStyle.fontSize,
         labelStyle.fontWeight
@@ -15141,7 +16126,7 @@ function compileGeoMap(spec, options) {
     height: contentHeight,
     animation: resolvedAnimation,
     watermark,
-    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth19(text, fontSize), height: fontSize })),
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth20(text, fontSize), height: fontSize })),
     warnings: compileWarnings,
     mapSize: { width: fullArea.width, height: mapAreaHeight },
     focus: resolvedFocus
@@ -15517,7 +16502,7 @@ function emptyLayout3(chrome, theme, options, watermark) {
     height: options.height,
     animation: void 0,
     watermark,
-    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth19(text, fontSize), height: fontSize })),
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth20(text, fontSize), height: fontSize })),
     warnings: [],
     mapSize: { width: 0, height: 0 },
     focus: null
@@ -15525,6 +16510,7 @@ function emptyLayout3(chrome, theme, options, watermark) {
 }
 
 // src/graphs/compile-graph.ts
+import { mergeThemeConfig as mergeThemeConfig3 } from "@opendata-ai/openchart-core";
 import {
   adaptTheme as adaptTheme3,
   computeChrome as computeChrome4,
@@ -15624,8 +16610,8 @@ function hexWithOpacity(hex, opacity) {
 }
 function computeDegrees(nodes, edges) {
   const degrees = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
-    degrees.set(node.id, 0);
+  for (const node2 of nodes) {
+    degrees.set(node2.id, 0);
   }
   for (const edge of edges) {
     degrees.set(edge.source, (degrees.get(edge.source) ?? 0) + 1);
@@ -15687,8 +16673,8 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
       const domain = scaleConfig?.domain && scaleConfig.domain.length === 2 ? scaleConfig.domain : [colorMin, colorMax];
       const range = scaleConfig?.range && scaleConfig.range.length >= 2 ? scaleConfig.range : [palette[0], palette[palette.length - 1]];
       const colorScale = scaleLinear5().domain(domain).range(range);
-      colorFn = (node) => {
-        const val = Number(node[field]);
+      colorFn = (node2) => {
+        const val = Number(node2[field]);
         return Number.isFinite(val) ? colorScale(val) : theme.colors.categorical[0];
       };
     } else {
@@ -15699,7 +16685,7 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
       );
       const range = scaleConfig?.range && scaleConfig.range.length > 0 ? scaleConfig.range : theme.colors.categorical;
       const ordinalScale = scaleOrdinal2().domain(domain).range(range);
-      colorFn = (node) => ordinalScale(String(node[field] ?? ""));
+      colorFn = (node2) => ordinalScale(String(node2[field] ?? ""));
     }
   }
   const defaultColor = theme.colors.categorical[0];
@@ -15726,48 +16712,48 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
     const range = scaleConfig?.range && scaleConfig.range.length >= 2 ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])] : [0, 1];
     labelPriorityScale = scaleLinear5().domain(domain).range(range);
   }
-  return nodes.map((node) => {
+  return nodes.map((node2) => {
     let radius = DEFAULT_NODE_RADIUS;
     if (sizeScale && encoding.nodeSize?.field) {
-      const val = Number(node[encoding.nodeSize.field]);
+      const val = Number(node2[encoding.nodeSize.field]);
       if (Number.isFinite(val)) {
         radius = sizeScale(val);
       }
     }
     let opacity = 1;
     if (opacityScale && encoding.nodeOpacity?.field) {
-      const val = Number(node[encoding.nodeOpacity.field]);
+      const val = Number(node2[encoding.nodeOpacity.field]);
       if (Number.isFinite(val)) {
         opacity = opacityScale(val);
       }
     }
-    const fill = colorFn ? colorFn(node) : defaultColor;
+    const fill = colorFn ? colorFn(node2) : defaultColor;
     const stroke = surface;
     let label;
     if (encoding.nodeLabel?.field) {
-      const labelVal = node[encoding.nodeLabel.field];
+      const labelVal = node2[encoding.nodeLabel.field];
       label = labelVal != null ? String(labelVal) : void 0;
     } else {
-      label = node.id;
+      label = node2.id;
     }
     let labelPriority;
     if (labelPriorityScale && encoding.nodeLabelPriority?.field) {
-      const val = Number(node[encoding.nodeLabelPriority.field]);
+      const val = Number(node2[encoding.nodeLabelPriority.field]);
       labelPriority = Number.isFinite(val) ? labelPriorityScale(val) : 0;
     } else {
-      const degree = degrees.get(node.id) ?? 0;
+      const degree = degrees.get(node2.id) ?? 0;
       labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
     }
-    const { id: _id, ...rest } = node;
-    const data = { id: node.id, ...rest };
-    const override = nodeOverrides?.[node.id];
+    const { id: _id, ...rest } = node2;
+    const data = { id: node2.id, ...rest };
+    const override = nodeOverrides?.[node2.id];
     const finalFill = override?.fill ?? fill;
     const finalRadius = override?.radius ?? radius;
     const finalStrokeWidth = override?.strokeWidth ?? DEFAULT_STROKE_WIDTH;
     const finalStroke = override?.stroke ?? stroke;
     const finalLabelPriority = override?.alwaysShowLabel ? Infinity : labelPriority;
     return {
-      id: node.id,
+      id: node2.id,
       radius: finalRadius,
       fill: finalFill,
       stroke: finalStroke,
@@ -15871,30 +16857,30 @@ function resolveEdgeVisuals(edges, encoding, theme, nodeFills) {
 // src/graphs/community.ts
 function assignCommunities(nodes, clusteringField) {
   if (!clusteringField) return;
-  for (const node of nodes) {
-    const value = node.data[clusteringField];
-    node.community = value != null ? String(value) : void 0;
+  for (const node2 of nodes) {
+    const value = node2.data[clusteringField];
+    node2.community = value != null ? String(value) : void 0;
   }
 }
 function buildCommunityColorMap(nodes, theme) {
   const colorMap = /* @__PURE__ */ new Map();
   const palette = theme.colors.categorical;
   let colorIndex = 0;
-  for (const node of nodes) {
-    if (node.community != null && !colorMap.has(node.community)) {
-      colorMap.set(node.community, palette[colorIndex % palette.length]);
+  for (const node2 of nodes) {
+    if (node2.community != null && !colorMap.has(node2.community)) {
+      colorMap.set(node2.community, palette[colorIndex % palette.length]);
       colorIndex++;
     }
   }
   return colorMap;
 }
 function applyCommunityColors(nodes, colorMap) {
-  for (const node of nodes) {
-    if (node.community != null) {
-      const communityColor = colorMap.get(node.community);
+  for (const node2 of nodes) {
+    if (node2.community != null) {
+      const communityColor = colorMap.get(node2.community);
       if (communityColor) {
-        node.fill = communityColor;
-        node.stroke = darkenColor(communityColor);
+        node2.fill = communityColor;
+        node2.stroke = darkenColor(communityColor);
       }
     }
   }
@@ -15966,9 +16952,9 @@ function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeC
   let entries;
   if (hasCommunities && communityColorMap.size > 0) {
     const counts = /* @__PURE__ */ new Map();
-    for (const node of nodes) {
-      if (node.community != null) {
-        counts.set(node.community, (counts.get(node.community) ?? 0) + 1);
+    for (const node2 of nodes) {
+      if (node2.community != null) {
+        counts.set(node2.community, (counts.get(node2.community) ?? 0) + 1);
       }
     }
     entries = [...communityColorMap.entries()].map(([label, color]) => ({
@@ -15981,10 +16967,10 @@ function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeC
   } else if (nodeColorField) {
     const categoryColors = /* @__PURE__ */ new Map();
     const categoryCounts = /* @__PURE__ */ new Map();
-    for (const node of nodes) {
-      const category = String(node.data[nodeColorField] ?? node.label ?? node.id);
+    for (const node2 of nodes) {
+      const category = String(node2.data[nodeColorField] ?? node2.label ?? node2.id);
       if (!categoryColors.has(category)) {
-        categoryColors.set(category, node.fill);
+        categoryColors.set(category, node2.fill);
       }
       categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
     }
@@ -16035,16 +17021,16 @@ function buildEdgeLegend(edges, encoding) {
 }
 function buildGraphTooltips(nodes) {
   const descriptors = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
+  for (const node2 of nodes) {
     const fields = [];
-    if (node.community != null) {
+    if (node2.community != null) {
       fields.push({
         label: "Community",
-        value: node.community,
-        color: node.fill
+        value: node2.community,
+        color: node2.fill
       });
     }
-    for (const [key, value] of Object.entries(node.data)) {
+    for (const [key, value] of Object.entries(node2.data)) {
       if (key === "id") continue;
       if (value == null) continue;
       fields.push({
@@ -16052,8 +17038,8 @@ function buildGraphTooltips(nodes) {
         value: typeof value === "number" ? graphNumberFormatter(value) : String(value)
       });
     }
-    descriptors.set(node.id, {
-      title: node.label ?? node.id,
+    descriptors.set(node2.id, {
+      title: node2.label ?? node2.id,
       fields
     });
   }
@@ -16096,7 +17082,8 @@ function compileGraph(spec, options) {
   }
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? graphSpec.watermark : options.watermark ?? true;
-  const mergedThemeConfig = options.theme ? { ...graphSpec.theme, ...options.theme } : graphSpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig3(graphSpec.theme, options.theme);
   let theme = resolveTheme4(mergedThemeConfig);
   if (options.darkMode) {
     theme = adaptTheme3(theme);
@@ -16262,30 +17249,19 @@ var DEFAULT_COLLISION_PADDING = 5;
 
 // src/layout/dimensions.ts
 import {
-  AXIS_TITLE_TRAILING_PAD as AXIS_TITLE_TRAILING_PAD3,
-  axisTitleOffset as axisTitleOffset4,
   BREAKPOINT_COMPACT_MAX as BREAKPOINT_COMPACT_MAX3,
   computeChrome as computeChrome5,
-  computeFieldFormatContext as computeFieldFormatContext6,
-  defaultNumberFormatter as defaultNumberFormatter9,
-  estimateTextWidth as estimateTextWidth21,
-  getHeightClass as getHeightClass2,
+  estimateTextWidth as estimateTextWidth22,
+  getHeightClass as getHeightClass3,
   HPAD_COMPACT_FRACTION as HPAD_COMPACT_FRACTION3,
   HPAD_COMPACT_MIN as HPAD_COMPACT_MIN3,
   isAxislessMark as isAxislessMark2,
-  LABEL_GAP_COMPACT as LABEL_GAP_COMPACT2,
-  LABEL_GAP_DEFAULT as LABEL_GAP_DEFAULT2,
-  MAX_LEFT_LABEL_FRACTION_COMPACT as MAX_LEFT_LABEL_FRACTION_COMPACT2,
-  MAX_LEFT_LABEL_FRACTION_DEFAULT as MAX_LEFT_LABEL_FRACTION_DEFAULT2,
-  MAX_LEFT_LABEL_FRACTION_MEDIUM as MAX_LEFT_LABEL_FRACTION_MEDIUM2,
-  MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX as MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX2,
   NARROW_VIEWPORT_MAX as NARROW_VIEWPORT_MAX3,
-  resolveNumberFormatter as resolveNumberFormatter6,
   TOP_PAD_EXTRA_NARROW as TOP_PAD_EXTRA_NARROW2
 } from "@opendata-ai/openchart-core";
 
 // src/layout/metrics.ts
-import { estimateTextWidth as estimateTextWidth20 } from "@opendata-ai/openchart-core";
+import { estimateTextWidth as estimateTextWidth21 } from "@opendata-ai/openchart-core";
 var DEFAULT_LABEL_FONT_SIZE = 10;
 var DEFAULT_VALUE_FONT_SIZE = 22;
 var LABEL_LINE_HEIGHT_RATIO = 1.4;
@@ -16318,7 +17294,7 @@ function computeMetricBar(metrics, metricsTopY, metricsArea, remainingChartHeigh
   const cellWidth = metricsArea.width / metrics.length;
   for (const metric of metrics) {
     const text = valueRunText(metric);
-    const measured = measureText ? measureText(text, fonts.value, 510).width : estimateTextWidth20(text, fonts.value, 510);
+    const measured = measureText ? measureText(text, fonts.value, 510).width : estimateTextWidth21(text, fonts.value, 510);
     if (measured > cellWidth - CELL_INNER_PAD) return void 0;
   }
   const labelLine = fonts.label * LABEL_LINE_HEIGHT_RATIO;
@@ -16343,10 +17319,6 @@ function computeMetricBar(metrics, metricsTopY, metricsArea, remainingChartHeigh
 function metricFonts(theme) {
   return { label: theme.fonts.sizes.metricLabel, value: theme.fonts.sizes.metricValue };
 }
-function legendLayoutHasContent(legendLayout) {
-  if (legendLayout.type === "continuous") return legendLayout.bounds.height > 0;
-  return "entries" in legendLayout && legendLayout.entries.length > 0;
-}
 var MIN_CHART_WIDTH = 60;
 var MIN_CHART_HEIGHT2 = 40;
 var PLOT_SHARE_MAX = 0.4;
@@ -16370,7 +17342,7 @@ function getSparklinePad(spec) {
     bottom: hasDots ? Math.max(strokePad, dotPad) : strokePad
   };
 }
-function computeDimensions(spec, options, legendLayout, theme, strategy, watermark = true, plan) {
+function computeDimensions(spec, options, legendLayout, theme, strategy, watermark, plan, reserveReferenceLabels = true) {
   const { width, height } = options;
   const padding = scalePadding(theme.spacing.padding, width, height);
   const hPad = width < BREAKPOINT_COMPACT_MAX3 ? Math.max(Math.round(padding * HPAD_COMPACT_FRACTION3), HPAD_COMPACT_MIN3) : padding;
@@ -16381,21 +17353,17 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
   if (isSparkline && !userExplicit.chrome) {
     chromeMode = "hidden";
   }
-  const bottomLegendReservation = plan ? hasLegendContent(plan.legendContent) && plan.legendContent.position === "bottom" ? plan.legendContent.height + legendGap(width) : 0 : legendLayoutHasContent(legendLayout) && legendLayout.position === "bottom" ? legendLayout.bounds.height + legendGap(width) : 0;
-  const isCrampedHeight = getHeightClass2(height) === "cramped";
-  const chrome = plan?.chrome ?? computeChrome5(
-    chromeToInput(spec.chrome),
-    theme,
+  const bottomLegendReservation = hasLegendContent(plan.legendContent) && plan.legendContent.position === "bottom" ? plan.legendContent.height + legendGap(width) : 0;
+  const isCrampedHeight = getHeightClass3(height) === "cramped";
+  const chrome = { ...plan.chrome };
+  const referenceReserve = referenceLabelReserve(
+    reserveReferenceLabels ? spec.annotations : [],
     width,
-    options.measureText,
-    chromeMode,
-    padding,
-    watermark,
-    bottomLegendReservation,
-    isCrampedHeight
+    options.measureText ? (text, font) => options.measureText(text, font.fontSize, font.fontWeight).width : heuristicMeasure
   );
   const chromeLayout = resolveChromeLayout(spec, options);
-  const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight : height;
+  const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight + (options.footnoteReserve ?? 0) : height;
+  if (chromeLayout === "grow") chrome.grownHeight = effectiveHeight - height;
   if (isSparkline) {
     const total2 = { x: 0, y: 0, width, height: effectiveHeight };
     const sparkPad = getSparklinePad(spec);
@@ -16404,10 +17372,10 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     const margins2 = {
       top: chrome.topHeight + sparkPad.top,
       right: sparkPad.right,
-      bottom: chrome.bottomHeight + sparkPad.bottom + xAxisSpace,
+      bottom: chrome.bottomHeight + sparkPad.bottom + xAxisSpace + (options.footnoteReserve ?? 0),
       left: sparkPad.left + yAxisSpace
     };
-    if (userExplicit.legend && legendLayoutHasContent(legendLayout)) {
+    if (userExplicit.legend && hasLegendContent(plan.legendContent)) {
       const gap = legendGap(width);
       if (legendLayout.position === "right" || legendLayout.position === "bottom-right") {
         margins2.right += legendLayout.bounds.width + 8;
@@ -16437,33 +17405,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
   const total = { x: 0, y: 0, width, height: effectiveHeight };
   const isRadial = isAxislessMark2(spec.markType);
   const encoding = spec.encoding;
-  const xAxisSuppressed = encoding.x?.axis === false;
-  const xAxis = !xAxisSuppressed && encoding.x?.axis;
-  const hasXAxisLabel = !!xAxis?.title;
-  const xTickAngle = xAxis?.labelAngle;
-  let xAxisHeight;
-  if (plan) {
-    xAxisHeight = plan.xAxisExtent;
-  } else if (isRadial || xAxisSuppressed) {
-    xAxisHeight = 0;
-  } else if (xTickAngle && Math.abs(xTickAngle) > 10) {
-    const angleRad = Math.abs(xTickAngle) * (Math.PI / 180);
-    const xField = encoding.x?.field;
-    let maxLabelWidth = 40;
-    if (xField) {
-      for (const row of spec.data) {
-        const label = String(row[xField] ?? "");
-        const w = estimateTextWidth21(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
-        if (w > maxLabelWidth) maxLabelWidth = w;
-      }
-    }
-    const rotatedHeight = maxLabelWidth * Math.sin(angleRad) + 6;
-    const labelHeight = Math.min(rotatedHeight, 120);
-    xAxisHeight = hasXAxisLabel ? labelHeight + 20 : labelHeight;
-  } else {
-    const base = theme.spacing.xAxisHeight;
-    xAxisHeight = hasXAxisLabel ? base + 22 : base;
-  }
+  const xAxisHeight = plan.xAxisExtent;
   const yIsInlinePre = yTickPositionIsInline(encoding.y, spec.markType);
   const inlineTickOverhang = yIsInlinePre ? theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD : 0;
   const topAxisGap = isRadial && chrome.topHeight === 0 ? 0 : axisMargin + inlineTickOverhang;
@@ -16473,7 +17415,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
   const wantsSearch = !!spec.seriesSearch && chromeMode !== "hidden" && !isCrampedHeight;
   const searchReservation = wantsSearch ? SERIES_SEARCH_INPUT_HEIGHT + SERIES_SEARCH_GAP : 0;
   const margins = {
-    top: topPad + chrome.topHeight + tentativeMetricsHeight + searchReservation,
+    top: topPad + chrome.topHeight + tentativeMetricsHeight + searchReservation + referenceReserve.top,
     right: hPad + (isRadial ? hPad : axisMargin),
     bottom: bottomMargin(chrome.bottomHeight, padding, xAxisHeight),
     left: hPad + (isRadial ? hPad : axisMargin)
@@ -16485,7 +17427,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     seriesCount,
     labelsHiddenByStrategy,
     labelsDensityNone: labelDensity === "none",
-    endpointLabelsDemoted: plan?.endpointLabelsDemoted
+    endpointLabelsDemoted: plan.endpointLabelsDemoted
   });
   let endpointWidth = 0;
   if (sup.showEndpointLabels) {
@@ -16507,7 +17449,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
         const label = String(row[colorField] ?? "");
         if (!seen.has(label)) {
           seen.add(label);
-          const w = estimateTextWidth21(label, 11, 600);
+          const w = estimateTextWidth22(label, 11, 600);
           if (w > maxLabelWidth) maxLabelWidth = w;
         }
       }
@@ -16516,138 +17458,18 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
       }
     }
   }
-  if (strategy?.annotationPosition !== "tooltip-only" && spec.annotations.length > 0 && encoding.x) {
-    const xField = encoding.x.field;
-    let maxX;
-    for (const row of spec.data) {
-      const v = row[xField];
-      if (v != null && (maxX == null || String(v) >= String(maxX))) maxX = v;
-    }
-    if (maxX != null) {
-      const maxXStr = String(maxX);
-      for (const ann of spec.annotations) {
-        if (ann.type === "text" && String(ann.x) === maxXStr) {
-          const textWidth = estimateTextWidth21(ann.text, ann.fontSize ?? 11, ann.fontWeight ?? 600);
-          const dx = ann.offset?.dx ?? 0;
-          const anchor = ann.anchor ?? "auto";
-          const baseRightExtent = anchor === "right" ? textWidth : anchor === "left" ? 0 : textWidth / 2;
-          const rightOverflow = Math.max(0, baseRightExtent + dx);
-          if (rightOverflow > 0) {
-            margins.right = Math.max(margins.right, hPad + rightOverflow + 12);
-          }
-        }
-      }
-    }
-  }
-  const yAxisSuppressed = encoding.y?.axis === false;
-  const yIsInline = yIsInlinePre;
-  if (encoding.y && !isRadial && !yAxisSuppressed && !yIsInline) {
-    const isBinnedBar = isBinnedBarEncoding(spec.markType, encoding);
-    if (!plan && !isBinnedBar && (spec.markType === "bar" || spec.markType === "circle" || spec.markType === "lollipop" || encoding.y.type === "nominal" || encoding.y.type === "ordinal")) {
-      const yField = encoding.y.field;
-      const yLabelField = encoding.y.axis?.labelField;
-      let maxLabelWidth = 0;
-      for (const row of spec.data) {
-        const label = String(row[yField] ?? "");
-        let w = estimateTextWidth21(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
-        if (yLabelField) {
-          const subtitle = String(row[yLabelField] ?? "");
-          if (subtitle) {
-            const gap = theme.fonts.sizes.axisTick * 0.6;
-            const subtitleWidth = estimateTextWidth21(
-              subtitle,
-              theme.fonts.sizes.axisTick,
-              theme.fonts.weights.normal
-            );
-            w += gap + subtitleWidth;
-          }
-        }
-        if (w > maxLabelWidth) maxLabelWidth = w;
-      }
-      if (maxLabelWidth > 0) {
-        const labelGap = width < NARROW_VIEWPORT_MAX3 ? LABEL_GAP_COMPACT2 : LABEL_GAP_DEFAULT2;
-        const maxLeftFraction = width < BREAKPOINT_COMPACT_MAX3 ? MAX_LEFT_LABEL_FRACTION_COMPACT2 : width < MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX2 ? MAX_LEFT_LABEL_FRACTION_MEDIUM2 : MAX_LEFT_LABEL_FRACTION_DEFAULT2;
-        const maxLeftReserved = Math.floor(width * maxLeftFraction);
-        const reserved = Math.min(hPad + maxLabelWidth + labelGap, maxLeftReserved);
-        margins.left = Math.max(margins.left, reserved);
-      }
-    } else if ((encoding.y.type === "quantitative" || encoding.y.type === "temporal") && !plan) {
-      const yField = encoding.y.field;
-      const yAxisFormat = encoding.y.axis?.format;
-      let maxAbsVal = 0;
-      for (const row of spec.data) {
-        const v = Number(row[yField]);
-        if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
-      }
-      const ctx = computeFieldFormatContext6(fieldIterable(spec.data, yField));
-      let sampleLabel;
-      if (yAxisFormat) {
-        const fmt2 = resolveNumberFormatter6(yAxisFormat, ctx);
-        sampleLabel = fmt2 ? fmt2(maxAbsVal) : String(maxAbsVal);
-      } else {
-        sampleLabel = defaultNumberFormatter9({ ...ctx, extent: ctx.extent ?? [0, maxAbsVal] })(
-          maxAbsVal
-        );
-      }
-      const negPrefix = spec.data.some((r) => Number(r[yField]) < 0) ? "-" : "";
-      const labelEst = negPrefix + sampleLabel;
-      const labelWidth = estimateTextWidth21(
-        labelEst,
-        theme.fonts.sizes.axisTick,
-        theme.fonts.weights.normal
-      );
-      margins.left = Math.max(margins.left, hPad + labelWidth + 10);
-    }
-  }
-  const yAxis = encoding.y?.axis;
-  if (yAxis && (yAxis.title || yAxis.label) && !isRadial && !plan) {
-    const yFieldForTitle = encoding.y?.field;
-    const yAxisFormatForTitle = yAxis?.format;
-    let estTickLabelWidth = 0;
-    if (yFieldForTitle && !yIsInlinePre && (encoding.y?.type === "quantitative" || encoding.y?.type === "temporal")) {
-      let maxAbsValForTitle = 0;
-      for (const row of spec.data) {
-        const v = Number(row[yFieldForTitle]);
-        if (Number.isFinite(v) && Math.abs(v) > maxAbsValForTitle) maxAbsValForTitle = Math.abs(v);
-      }
-      const ctxForTitle = computeFieldFormatContext6(fieldIterable(spec.data, yFieldForTitle));
-      let sampleLabelForTitle;
-      if (yAxisFormatForTitle) {
-        const fmt2 = resolveNumberFormatter6(yAxisFormatForTitle, ctxForTitle);
-        sampleLabelForTitle = fmt2 ? fmt2(maxAbsValForTitle) : String(maxAbsValForTitle);
-      } else {
-        sampleLabelForTitle = defaultNumberFormatter9({
-          ...ctxForTitle,
-          extent: ctxForTitle.extent ?? [0, maxAbsValForTitle]
-        })(maxAbsValForTitle);
-      }
-      const negPrefixForTitle = spec.data.some((r) => Number(r[yFieldForTitle]) < 0) ? "-" : "";
-      estTickLabelWidth = estimateTextWidth21(
-        negPrefixForTitle + sampleLabelForTitle,
-        theme.fonts.sizes.axisTick,
-        theme.fonts.weights.normal
-      );
-    }
-    const titleFontSize = theme.fonts.sizes.body;
-    const offset = axisTitleOffset4(estTickLabelWidth, titleFontSize, width, yIsInlinePre);
-    const halfGlyph = Math.ceil(titleFontSize / 2);
-    const rotatedLabelMargin = offset + halfGlyph + (width < BREAKPOINT_COMPACT_MAX3 ? 0 : AXIS_TITLE_TRAILING_PAD3);
-    margins.left = Math.max(margins.left, hPad + rotatedLabelMargin);
-  }
-  if (plan) {
-    margins.left = Math.max(margins.left, plan.leftGutter);
-  }
+  margins.left = Math.max(margins.left, plan.leftGutter);
   if (options.rightAxisReserve && options.rightAxisReserve > 0) {
     margins.right = Math.max(margins.right, hPad + options.rightAxisReserve);
   }
   if (options.footnoteReserve && options.footnoteReserve > 0) {
     margins.bottom += options.footnoteReserve;
   }
-  const legendHasEntries = plan ? hasLegendContent(plan.legendContent) : legendLayoutHasContent(legendLayout);
-  const legendPos = plan ? plan.legendContent.position : legendLayout.position;
-  const legendHeight = plan ? plan.legendContent.height : legendLayout.bounds.height;
-  const legendBoundsWidth = plan ? plan.legendContent.legendWidth : legendLayout.bounds.width;
-  const sizeLegend = plan?.sizeLegendContent;
+  const legendHasEntries = hasLegendContent(plan.legendContent);
+  const legendPos = plan.legendContent.position;
+  const legendHeight = plan.legendContent.height;
+  const legendBoundsWidth = plan.legendContent.legendWidth;
+  const sizeLegend = plan.sizeLegendContent;
   const colorLegendInGutter = legendHasEntries && (legendPos === "right" || legendPos === "bottom-right");
   const hasTopLegend = legendHasEntries && legendPos === "top";
   if (legendHasEntries) {
@@ -16658,7 +17480,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
   }
   const colorReserve = colorLegendInGutter ? legendBoundsWidth + 8 : 0;
   const sizeReserve = sizeLegend ? sizeLegend.width + SIZE_LEGEND_GAP : 0;
-  margins.right += Math.max(colorReserve, sizeReserve);
+  margins.right += Math.max(colorReserve, sizeReserve) + referenceReserve.right;
   const effectiveAxisGap = hasTopLegend ? inlineTickOverhang : topAxisGap;
   margins.top += effectiveAxisGap;
   let chartArea = {
@@ -16685,7 +17507,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     const fallbackEffectiveAxisGap = hasTopLegend ? inlineTickOverhang : fallbackTopAxisGap;
     const newTop = topPad + fallbackChrome.topHeight + tentativeMetricsHeight + searchReservation;
     const topDelta = margins.top - newTop;
-    const newBottom = bottomMargin(fallbackChrome.bottomHeight, padding, xAxisHeight);
+    const newBottom = bottomMargin(fallbackChrome.bottomHeight, padding, xAxisHeight) + (options.footnoteReserve ?? 0);
     const bottomDelta = margins.bottom - newBottom;
     if (topDelta > 0 || bottomDelta > 0) {
       const gap = legendGap(width);
@@ -16804,39 +17626,52 @@ function facetMinHeight(panelCount, columns) {
   const rows = Math.ceil(panelCount / columns);
   return rows * (MIN_PANEL_HEIGHT + HEADER_HEIGHT + X_AXIS_HEIGHT) + (rows - 1) * PANEL_GAP;
 }
-function computeFacetGrid(facetValues, requestedColumns, totalArea, outerAxisReservation) {
+function computeFacetGrid(facetValues, requestedColumns, totalArea, outerAxisReservation, referenceInsets) {
   const n = facetValues.length;
   if (n === 0) return { panels: [], columns: 0, rows: 0 };
   const usableWidth = totalArea.width - outerAxisReservation.left;
   let columns = Math.min(requestedColumns ?? autoColumns(n, usableWidth), n);
   while (columns > 1) {
     const panelWidth2 = (usableWidth - (columns - 1) * PANEL_GAP) / columns;
-    if (panelWidth2 >= MIN_PANEL_WIDTH) break;
+    const innerAxis = referenceInsets?.innerAxisWidth ?? 0;
+    const right = referenceInsets?.measure(panelWidth2 - innerAxis).right ?? 0;
+    if (panelWidth2 - innerAxis - right >= MIN_PANEL_WIDTH) break;
     columns--;
   }
   const rows = Math.ceil(n / columns);
   const panelWidth = Math.max(0, (usableWidth - (columns - 1) * PANEL_GAP) / columns);
   const xAxisPerRow = outerAxisReservation.bottom;
   const usableHeight = totalArea.height;
+  const topInset = referenceInsets?.measure(panelWidth - (columns > 1 ? referenceInsets.innerAxisWidth : 0)).top ?? 0;
   const panelHeight = Math.max(
     0,
-    (usableHeight - rows * (HEADER_HEIGHT + xAxisPerRow) - (rows - 1) * PANEL_GAP) / rows
+    (usableHeight - rows * (HEADER_HEIGHT + topInset + xAxisPerRow) - (rows - 1) * PANEL_GAP) / rows
   );
-  const rowStride = HEADER_HEIGHT + panelHeight + xAxisPerRow + PANEL_GAP;
+  const rowStride = HEADER_HEIGHT + topInset + panelHeight + xAxisPerRow + PANEL_GAP;
   const panels = [];
   for (let i = 0; i < n; i++) {
     const col = i % columns;
     const row = Math.floor(i / columns);
     const x = totalArea.x + outerAxisReservation.left + col * (panelWidth + PANEL_GAP);
     const y = totalArea.y + row * rowStride;
+    const leftInset = col > 0 ? referenceInsets?.innerAxisWidth ?? 0 : 0;
+    const reserve = referenceInsets?.measure(panelWidth - leftInset);
     panels.push({
       key: facetValues[i],
       area: {
-        x,
-        y: y + HEADER_HEIGHT,
-        width: panelWidth,
+        x: x + leftInset,
+        y: y + HEADER_HEIGHT + topInset,
+        width: Math.max(0, panelWidth - leftInset - (reserve?.right ?? 0)),
         height: panelHeight
       },
+      ...referenceInsets ? {
+        referenceContainer: {
+          x: x + leftInset,
+          y: y + HEADER_HEIGHT,
+          width: panelWidth - leftInset,
+          height: topInset + panelHeight
+        }
+      } : {},
       headerPos: {
         x: x + panelWidth / 2,
         y: y + HEADER_HEIGHT * 0.6
@@ -16845,7 +17680,14 @@ function computeFacetGrid(facetValues, requestedColumns, totalArea, outerAxisRes
       col
     });
   }
-  return { panels, columns, rows };
+  return {
+    panels,
+    columns,
+    rows,
+    ...referenceInsets ? {
+      minimumHeight: rows * (MIN_PANEL_HEIGHT + HEADER_HEIGHT + topInset + xAxisPerRow) + (rows - 1) * PANEL_GAP
+    } : {}
+  };
 }
 
 // src/layout/gridlines.ts
@@ -16878,12 +17720,13 @@ function computeGridlines(axes, chartArea, showVertical = false) {
 }
 
 // src/sankey/compile-sankey.ts
+import { mergeThemeConfig as mergeThemeConfig4 } from "@opendata-ai/openchart-core";
 import {
   adaptTheme as adaptTheme4,
   buildD3Formatter as buildD3Formatter3,
   computeChrome as computeChrome6,
-  defaultNumberFormatter as defaultNumberFormatter10,
-  estimateTextWidth as estimateTextWidth22,
+  defaultNumberFormatter as defaultNumberFormatter9,
+  estimateTextWidth as estimateTextWidth23,
   resolveTheme as resolveTheme5
 } from "@opendata-ai/openchart-core";
 
@@ -16977,12 +17820,12 @@ function buildNodeColorMap(nodes, palette, colorField, data, sourceField, target
     }
     const categoryIndex = /* @__PURE__ */ new Map();
     let nextIdx = 0;
-    for (const node of nodes) {
-      const category = nodeCategoryMap.get(node.id) ?? node.id;
+    for (const node2 of nodes) {
+      const category = nodeCategoryMap.get(node2.id) ?? node2.id;
       if (!categoryIndex.has(category)) {
         categoryIndex.set(category, nextIdx++);
       }
-      colorMap.set(node.id, pickColor(palette, categoryIndex.get(category)));
+      colorMap.set(node2.id, pickColor(palette, categoryIndex.get(category)));
     }
   } else {
     for (let i = 0; i < nodes.length; i++) {
@@ -17012,11 +17855,11 @@ function resolveOtherConfig(other) {
 }
 function bucketSmallNodes(nodes, cfg) {
   const byDepth = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
-    const depth = node.depth ?? 0;
+  for (const node2 of nodes) {
+    const depth = node2.depth ?? 0;
     const group = byDepth.get(depth);
-    if (group) group.push(node);
-    else byDepth.set(depth, [node]);
+    if (group) group.push(node2);
+    else byDepth.set(depth, [node2]);
   }
   const merged = /* @__PURE__ */ new Map();
   for (const [depth, group] of byDepth) {
@@ -17024,7 +17867,7 @@ function bucketSmallNodes(nodes, cfg) {
     if (total <= 0) continue;
     const small = group.filter((n) => (n.value ?? 0) / total < cfg.threshold);
     if (small.length < 2) continue;
-    for (const node of small) merged.set(node.id, `${OTHER_ID_PREFIX}${depth}`);
+    for (const node2 of small) merged.set(node2.id, `${OTHER_ID_PREFIX}${depth}`);
   }
   return merged;
 }
@@ -17057,8 +17900,8 @@ function labelsLeftForDepth(depth, maxDepth, nodeLabelAlign) {
   if (depth === 0 && maxDepth > 0) return true;
   return false;
 }
-function computeNodeLabel(node, maxDepth, theme, nodeWidth, nodeLabelAlign = "auto", containerWidth, padding) {
-  const depth = node.depth ?? 0;
+function computeNodeLabel(node2, maxDepth, theme, nodeWidth, nodeLabelAlign = "auto", containerWidth, padding) {
+  const depth = node2.depth ?? 0;
   const placeLeft = labelsLeftForDepth(depth, maxDepth, nodeLabelAlign);
   const style = {
     fontFamily: theme.fonts.family,
@@ -17067,10 +17910,10 @@ function computeNodeLabel(node, maxDepth, theme, nodeWidth, nodeLabelAlign = "au
     fill: theme.colors.text,
     lineHeight: 1.3
   };
-  const x0 = node.x0 ?? 0;
-  const x1 = node.x1 ?? nodeWidth;
-  const y0 = node.y0 ?? 0;
-  const y1 = node.y1 ?? 0;
+  const x0 = node2.x0 ?? 0;
+  const x1 = node2.x1 ?? nodeWidth;
+  const y0 = node2.y0 ?? 0;
+  const y1 = node2.y1 ?? 0;
   const midY = (y0 + y1) / 2;
   const pad = padding ?? 0;
   let maxWidth;
@@ -17084,7 +17927,7 @@ function computeNodeLabel(node, maxDepth, theme, nodeWidth, nodeLabelAlign = "au
   }
   if (placeLeft) {
     return {
-      text: node.label ?? node.id,
+      text: node2.label ?? node2.id,
       x: x0 - LABEL_GAP3,
       y: midY,
       style: { ...style, textAnchor: "end", dominantBaseline: "central" },
@@ -17093,7 +17936,7 @@ function computeNodeLabel(node, maxDepth, theme, nodeWidth, nodeLabelAlign = "au
     };
   }
   return {
-    text: node.label ?? node.id,
+    text: node2.label ?? node2.id,
     x: x1 + LABEL_GAP3,
     y: midY,
     style: { ...style, textAnchor: "start", dominantBaseline: "central" },
@@ -17115,7 +17958,8 @@ function compileSankey(spec, options) {
   const resolvedValueFormat = sankeySpec.encoding.value.format ?? sankeySpec.valueFormat;
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? sankeySpec.watermark : options.watermark ?? true;
-  const mergedThemeConfig = options.theme ? { ...sankeySpec.theme, ...options.theme } : sankeySpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig4(sankeySpec.theme, options.theme);
   const lightTheme = resolveTheme5(mergedThemeConfig);
   let theme = lightTheme;
   if (options.darkMode) {
@@ -17260,18 +18104,18 @@ function compileSankey(spec, options) {
   }
   const applyOtherLabels = (list) => {
     if (otherLabels.size === 0) return;
-    for (const node of list) {
-      const label = otherLabels.get(node.id);
-      if (label) node.label = label;
+    for (const node2 of list) {
+      const label = otherLabels.get(node2.id);
+      if (label) node2.label = label;
     }
   };
   applyOtherLabels(nodes);
   const nodeFmt = resolveNodeValueFormatter(nodes, resolvedValueFormat, flowFmt);
-  const labelBlockWidth = (node) => {
-    const name = node.label ?? node.id;
-    const nameWidth = estimateTextWidth22(name, labelFontSize, labelFontWeight);
-    const valueWidth = estimateTextWidth22(
-      formatFlowValue(node.value ?? 0, nodeFmt),
+  const labelBlockWidth = (node2) => {
+    const name = node2.label ?? node2.id;
+    const nameWidth = estimateTextWidth23(name, labelFontSize, labelFontWeight);
+    const valueWidth = estimateTextWidth23(
+      formatFlowValue(node2.value ?? 0, nodeFmt),
       labelFontSize,
       valueFontWeight
     );
@@ -17282,14 +18126,14 @@ function compileSankey(spec, options) {
     const cap = area3.width * MAX_LABEL_GUTTER;
     let left = 0;
     let right = 0;
-    for (const node of list) {
-      const depth = node.depth ?? 0;
-      const width = labelBlockWidth(node) + LABEL_GAP3;
+    for (const node2 of list) {
+      const depth = node2.depth ?? 0;
+      const width = labelBlockWidth(node2) + LABEL_GAP3;
       if (labelsLeftForDepth(depth, maxDepth2, nodeLabelAlign)) {
-        const need = width - ((node.x0 ?? 0) - area3.x);
+        const need = width - ((node2.x0 ?? 0) - area3.x);
         if (need > left) left = need;
       } else {
-        const need = width - (area3.x + area3.width - (node.x1 ?? 0));
+        const need = width - (area3.x + area3.width - (node2.x1 ?? 0));
         if (need > right) right = need;
       }
     }
@@ -17332,39 +18176,39 @@ function compileSankey(spec, options) {
     lineHeight: 1.3
   };
   const columnX0 = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
-    const d = node.depth ?? 0;
-    const x0 = node.x0 ?? 0;
+  for (const node2 of nodes) {
+    const d = node2.depth ?? 0;
+    const x0 = node2.x0 ?? 0;
     const current = columnX0.get(d);
     if (current === void 0 || x0 < current) columnX0.set(d, x0);
   }
-  const valueLabelFor = (node, depth, text) => {
+  const valueLabelFor = (node2, depth, text) => {
     const placedLeft = labelsLeftForDepth(depth, maxDepth, nodeLabelAlign);
     if (placedLeft || depth === maxDepth) return { text, style: valueStyle };
     const nextColumn = columnX0.get(depth + 1);
     if (nextColumn === void 0) return { text, style: valueStyle };
-    const available = nextColumn - LABEL_GAP3 - ((node.x1 ?? 0) + LABEL_GAP3);
-    const needed = estimateTextWidth22(node.label ?? node.id, labelFontSize, labelFontWeight) + VALUE_GAP + estimateTextWidth22(text, labelFontSize, valueFontWeight);
+    const available = nextColumn - LABEL_GAP3 - ((node2.x1 ?? 0) + LABEL_GAP3);
+    const needed = estimateTextWidth23(node2.label ?? node2.id, labelFontSize, labelFontWeight) + VALUE_GAP + estimateTextWidth23(text, labelFontSize, valueFontWeight);
     return needed <= available ? { text, style: valueStyle } : void 0;
   };
-  const nodeMarks = nodes.map((node) => {
-    const fill = nodeColorMap.get(node.id) ?? theme.colors.categorical[0];
-    const depth = node.depth ?? 0;
-    const merged = otherMembers.get(node.id);
-    const valueText = formatFlowValue(node.value ?? 0, nodeFmt);
+  const nodeMarks = nodes.map((node2) => {
+    const fill = nodeColorMap.get(node2.id) ?? theme.colors.categorical[0];
+    const depth = node2.depth ?? 0;
+    const merged = otherMembers.get(node2.id);
+    const valueText = formatFlowValue(node2.value ?? 0, nodeFmt);
     return {
       type: "sankeyNode",
-      x: node.x0 ?? 0,
-      y: node.y0 ?? 0,
-      width: (node.x1 ?? 0) - (node.x0 ?? 0),
-      height: (node.y1 ?? 0) - (node.y0 ?? 0),
+      x: node2.x0 ?? 0,
+      y: node2.y0 ?? 0,
+      width: (node2.x1 ?? 0) - (node2.x0 ?? 0),
+      height: (node2.y1 ?? 0) - (node2.y0 ?? 0),
       fill,
       // Explicit: a node is a solid block of flow, not an outlined box. Without
       // this the renderer inherits whatever stroke the SVG context carries.
       stroke: "none",
       cornerRadius: NODE_CORNER_RADIUS,
       label: computeNodeLabel(
-        node,
+        node2,
         maxDepth,
         theme,
         sankeySpec.nodeWidth,
@@ -17372,14 +18216,14 @@ function compileSankey(spec, options) {
         options.width,
         padding
       ),
-      valueLabel: valueLabelFor(node, depth, valueText),
-      nodeId: node.id,
-      value: node.value ?? 0,
+      valueLabel: valueLabelFor(node2, depth, valueText),
+      nodeId: node2.id,
+      value: node2.value ?? 0,
       depth,
-      data: merged ? { id: node.id, label: node.label, merged } : { id: node.id, label: node.label },
+      data: merged ? { id: node2.id, label: node2.label, merged } : { id: node2.id, label: node2.label },
       aria: {
         role: "img",
-        label: `${node.label}: ${valueText}`
+        label: `${node2.label}: ${valueText}`
       },
       animationIndex: 0
       // Reassigned below after sorting by depth
@@ -17529,22 +18373,22 @@ function resolveNodeValueFormatter(nodes, explicitFormat, fallback) {
   }
   return buildD3Formatter3(`,.${decimals}f`) ?? fallback;
 }
-var defaultFmt3 = defaultNumberFormatter10();
+var defaultFmt3 = defaultNumberFormatter9();
 function formatFlowValue(value, formatter) {
   if (formatter) return formatter(value);
   return defaultFmt3(value);
 }
 function buildTooltipDescriptors(nodes, links, formatter, nodeFormatter) {
   const descriptors = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
+  for (const node2 of nodes) {
     const fields = [
       {
         label: "Total flow",
-        value: formatFlowValue(node.value, nodeFormatter ?? formatter)
+        value: formatFlowValue(node2.value, nodeFormatter ?? formatter)
       }
     ];
-    descriptors.set(`node-${node.nodeId}`, {
-      title: node.label.text,
+    descriptors.set(`node-${node2.nodeId}`, {
+      title: node2.label.text,
       fields
     });
   }
@@ -17602,7 +18446,7 @@ function emptyLayout4(area3, chrome, theme, options, watermark) {
 }
 
 // src/tables/compile-table.ts
-import { computeChrome as computeChrome7, estimateTextWidth as estimateTextWidth23 } from "@opendata-ai/openchart-core";
+import { computeChrome as computeChrome7, estimateTextWidth as estimateTextWidth24 } from "@opendata-ai/openchart-core";
 
 // src/tables/bar-column.ts
 var NEGATIVE_BAR_COLOR = "#c44e52";
@@ -17726,9 +18570,9 @@ function computeCategoryColors(data, column, theme, darkMode) {
 // src/tables/format-cells.ts
 import {
   buildD3Formatter as buildD3Formatter4,
-  defaultNumberFormatter as defaultNumberFormatter11,
+  defaultNumberFormatter as defaultNumberFormatter10,
   formatDate as formatDate3,
-  resolveNumberFormatter as resolveNumberFormatter7
+  resolveNumberFormatter as resolveNumberFormatter6
 } from "@opendata-ai/openchart-core";
 function isNumericValue(value) {
   if (typeof value === "number") return Number.isFinite(value);
@@ -17748,7 +18592,7 @@ function formatCell(value, column) {
     };
   }
   if (column.format && isNumericValue(value)) {
-    const formatter = resolveNumberFormatter7(column.format, { surface: "table" }) ?? buildD3Formatter4(column.format);
+    const formatter = resolveNumberFormatter6(column.format, { surface: "table" }) ?? buildD3Formatter4(column.format);
     if (formatter) {
       return {
         value,
@@ -17760,7 +18604,7 @@ function formatCell(value, column) {
   if (isNumericValue(value)) {
     return {
       value,
-      formattedValue: defaultNumberFormatter11({ surface: "table" })(value),
+      formattedValue: defaultNumberFormatter10({ surface: "table" })(value),
       style
     };
   }
@@ -17780,13 +18624,13 @@ function formatCell(value, column) {
 function formatValueForSearch(value, column) {
   if (value == null) return "";
   if (column.format && isNumericValue(value)) {
-    const formatter = resolveNumberFormatter7(column.format, { surface: "table" }) ?? buildD3Formatter4(column.format);
+    const formatter = resolveNumberFormatter6(column.format, { surface: "table" }) ?? buildD3Formatter4(column.format);
     if (formatter) {
       return formatter(value);
     }
   }
   if (isNumericValue(value)) {
-    return defaultNumberFormatter11({ surface: "table" })(value);
+    return defaultNumberFormatter10({ surface: "table" })(value);
   }
   return String(value);
 }
@@ -18075,13 +18919,13 @@ function estimateColumnWidth(col, data, fontSize, paddingX) {
   if (col.image) return (col.image.width ?? 24) + paddingX;
   if (col.flag) return 60;
   const label = col.label ?? col.key;
-  const headerWidth = estimateTextWidth23(label, fontSize, 600) + paddingX;
+  const headerWidth = estimateTextWidth24(label, fontSize, 600) + paddingX;
   const sampleSize = Math.min(100, data.length);
   let maxDataWidth = 0;
   for (let i = 0; i < sampleSize; i++) {
     const val = data[i][col.key];
     const text = val == null ? "" : String(val);
-    const width = estimateTextWidth23(text, fontSize, 400) + paddingX;
+    const width = estimateTextWidth24(text, fontSize, 400) + paddingX;
     if (width > maxDataWidth) maxDataWidth = width;
   }
   return Math.max(MIN_WIDTH, headerWidth, maxDataWidth);
@@ -18445,12 +19289,13 @@ function compileTableLayout(spec, options, theme) {
 }
 
 // src/tilemap/compile-tilemap.ts
+import { mergeThemeConfig as mergeThemeConfig5 } from "@opendata-ai/openchart-core";
 import {
   adaptTheme as adaptTheme5,
   CATEGORICAL_PALETTE as CATEGORICAL_PALETTE3,
   computeChrome as computeChrome8,
-  estimateTextWidth as estimateTextWidth24,
-  getBreakpoint as getBreakpoint2,
+  estimateTextWidth as estimateTextWidth25,
+  getBreakpoint as getBreakpoint3,
   HPAD_COMPACT_FRACTION as HPAD_COMPACT_FRACTION4,
   HPAD_COMPACT_MIN as HPAD_COMPACT_MIN4,
   pickLabelColor as pickLabelColor4,
@@ -18496,7 +19341,8 @@ function compileTileMap(spec, options) {
   const tilemapSpec = normalized;
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? tilemapSpec.watermark : options.watermark ?? true;
-  const mergedThemeConfig = options.theme ? { ...tilemapSpec.theme, ...options.theme } : tilemapSpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig5(tilemapSpec.theme, options.theme);
   const lightTheme = resolveTheme6(mergedThemeConfig);
   let theme = lightTheme;
   if (options.darkMode) {
@@ -18518,7 +19364,7 @@ function compileTileMap(spec, options) {
     void 0,
     watermark
   );
-  const padding = getBreakpoint2(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN4, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION4)) : theme.spacing.padding;
+  const padding = getBreakpoint3(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN4, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION4)) : theme.spacing.padding;
   const chromeLayout = resolveChromeLayout(
     spec,
     options
@@ -18631,7 +19477,7 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
     });
     const hasEmptyTiles = tiles.some((t) => !t.hasData);
     const noDataLabel = "No data";
-    const noDataLabelWidth = estimateTextWidth24(noDataLabel, 11);
+    const noDataLabelWidth = estimateTextWidth25(noDataLabel, 11);
     const noDataBlockWidth2 = hasEmptyTiles ? NO_DATA_BAR_GAP + legendBarHeight + NO_DATA_LABEL_GAP2 + noDataLabelWidth : 0;
     const barWidth = Math.max(0, legendWidth - noDataBlockWidth2);
     const noDataX = legendX + barWidth + NO_DATA_BAR_GAP;
@@ -18688,7 +19534,7 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
     height: contentHeight,
     animation: resolvedAnimation,
     watermark,
-    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth24(text, fontSize), height: fontSize }))
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth25(text, fontSize), height: fontSize }))
   };
 }
 function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark, chromeLayout) {
@@ -18829,7 +19675,7 @@ function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDar
     height: contentHeight,
     animation: resolvedAnimation,
     watermark,
-    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth24(text, fontSize), height: fontSize }))
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth25(text, fontSize), height: fontSize }))
   };
 }
 function buildTileMark(opts) {
@@ -18955,7 +19801,7 @@ function countLegendRows(labels, availableWidth, fontSize) {
   let rows = 1;
   let offsetX = 0;
   for (let i = 0; i < labels.length; i++) {
-    const labelWidth = estimateTextWidth24(labels[i], fontSize);
+    const labelWidth = estimateTextWidth25(labels[i], fontSize);
     const entryWidth = LEGEND_SWATCH_SIZE + LEGEND_SWATCH_GAP + labelWidth + LEGEND_ENTRY_GAP;
     if (i > 0 && offsetX + entryWidth > availableWidth) {
       rows++;
@@ -18999,14 +19845,14 @@ function emptyLayout5(chrome, theme, options, watermark) {
     height: options.height,
     watermark,
     animation: void 0,
-    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth24(text, fontSize), height: fontSize }))
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth25(text, fontSize), height: fontSize }))
   };
 }
 
 // src/tooltips/compute.ts
 import {
   buildTemporalFormatter as buildTemporalFormatter2,
-  defaultNumberFormatter as defaultNumberFormatter12,
+  defaultNumberFormatter as defaultNumberFormatter11,
   formatDate as formatDate4,
   formatPercent as formatPercent4,
   getRepresentativeColor as getRepresentativeColor14
@@ -19020,7 +19866,7 @@ function formatValue2(value, fieldType, formatter) {
   }
   if (typeof value === "number") {
     if (formatter) return formatter(value);
-    return defaultNumberFormatter12()(value);
+    return defaultNumberFormatter11()(value);
   }
   return String(value);
 }
@@ -19342,7 +20188,7 @@ function computeRangeTooltips(spec, marks) {
     const endVal = Number(row[endCh.field]);
     if (Number.isFinite(startVal) && Number.isFinite(endVal)) {
       const delta = endVal - startVal;
-      const formatted = startFmt ? startFmt(delta) : defaultNumberFormatter12()(delta);
+      const formatted = startFmt ? startFmt(delta) : defaultNumberFormatter11()(delta);
       fields.push({ label: "Change", value: delta > 0 ? `+${formatted}` : formatted });
     }
     return { title, fields };
@@ -19470,8 +20316,8 @@ function computeBinnedBarTooltips(spec, marks) {
     const title = `${start} \u2013 ${end}`;
     if (encoding.tooltip) {
       const channels = Array.isArray(encoding.tooltip) ? encoding.tooltip : [encoding.tooltip];
+      if (channels.length === 0) continue;
       descriptors.set(`rect-${i}`, {
-        title,
         fields: buildExplicitTooltipFields(row, channels, fmtCache)
       });
       continue;
@@ -20198,7 +21044,7 @@ function applySpecSize(spec, options) {
   return {
     ...options,
     width: typeof sized.width === "number" ? sized.width : options.width,
-    height: typeof sized.height === "number" ? sized.height : options.height
+    height: typeof sized.height === "number" && !(options?.facetHeightGrown && (sized.chromeLayout ?? options.chromeLayout) === "grow") ? sized.height : options.height
   };
 }
 var MAX_FOOTNOTE_PASSES = 3;
@@ -20262,10 +21108,16 @@ function resolveScaleInvert(resolved) {
   return { topPixel: topPx, bottomPixel: bottomPx, topData, bottomData, scaleType };
 }
 function compileChart(spec, optionsInput) {
+  emitSpecWarnings(collectMarkOptionWarnings(spec), optionsInput?.onWarn);
+  return compileChartInternal(spec, optionsInput);
+}
+function compileChartInternal(spec, optionsInput) {
   const sugarWarnings = [];
-  const expandedSpec = spec && typeof spec === "object" && !Array.isArray(spec) ? expandSpecSugar(spec, sugarWarnings) : spec;
+  const expandedSpec = spec && typeof spec === "object" && !Array.isArray(spec) ? expandSpecSugar(spec, sugarWarnings, false) : spec;
   const options = applySpecSize(expandedSpec, optionsInput);
-  const { spec: normalized, warnings: normalizeWarnings } = compile(expandedSpec);
+  const { spec: normalized, warnings: normalizeWarnings } = compile(expandedSpec, {
+    markOptionWarnings: false
+  });
   emitSpecWarnings([...sugarWarnings, ...normalizeWarnings], options.onWarn);
   if ("type" in normalized && normalized.type === "table") {
     throw new Error("compileChart received a table spec. Use compileTable instead.");
@@ -20286,9 +21138,9 @@ function compileChart(spec, optionsInput) {
   if (rawTransforms && rawTransforms.length > 0) {
     chartSpec = { ...chartSpec, data: runTransforms(chartSpec.data, rawTransforms) };
   }
-  const breakpoint = getBreakpoint3(options.width);
-  const heightClass = getHeightClass3(options.height);
-  let strategy = getLayoutStrategy(breakpoint, heightClass);
+  const breakpoint = getBreakpoint4(options.width);
+  const heightClass = getHeightClass4(options.height);
+  let strategy = getLayoutStrategy2(breakpoint, heightClass);
   const economy = resolveChromeEconomy(options.width, options.height);
   const rawSpec = expandedSpec;
   const overrides = rawSpec.overrides;
@@ -20435,11 +21287,26 @@ function compileChart(spec, optionsInput) {
     watermark = false;
     chartSpec = { ...chartSpec, watermark: false };
   }
-  const mergedThemeConfig = options.theme ? { ...chartSpec.theme, ...options.theme } : chartSpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig6(chartSpec.theme, options.theme);
   let theme = resolveTheme7(mergedThemeConfig);
   if (options.darkMode) {
     theme = adaptTheme6(theme);
   }
+  const noteCapacity = chartSpec.autoThin ? annotationNoteCapacity(
+    chartSpec.annotations,
+    options.width,
+    theme,
+    options.measureText,
+    options.width < 400 && options.height >= 200 && chartSpec.compactAnnotationLimit != null
+  ) : 0;
+  const stableNoteReserve = computeNoteBandHeight2(noteCapacity, theme);
+  if (!options.frozenChartArea && stableNoteReserve > (options.footnoteReserve ?? 0)) {
+    return compileChartInternal(spec, {
+      ...optionsInput,
+      footnoteReserve: stableNoteReserve
+    });
+  }
   if (chartSpec.display === "sparkline") {
     chartSpec = applySparklineDefaults(chartSpec, theme);
   }
@@ -20492,20 +21359,23 @@ function compileChart(spec, optionsInput) {
   }
   const facetChannel = renderSpec.encoding.facet;
   if (facetChannel?.field) {
-    return compileFaceted(
+    const layout2 = compileFaceted(
       chartSpec,
       renderSpec,
       facetChannel,
       facetDirection,
-      options,
+      { ...options, onDiagnostic: void 0 },
       theme,
       strategy,
       watermark,
       resolvedAnimation,
       crosshair,
       spec,
-      optionsInput
+      { ...optionsInput, onDiagnostic: void 0 }
     );
+    const diagnostic = noteCapacityDiagnostic(layout2);
+    if (diagnostic) options.onDiagnostic?.(diagnostic);
+    return layout2;
   }
   const measure = createMeasureFn(options.measureText);
   const plan = resolveLayoutPlan(
@@ -20526,16 +21396,6 @@ function compileChart(spec, optionsInput) {
   );
   const dims = computeDimensions(chartSpec, options, legendStub, theme, strategy, watermark, plan);
   const chartArea = options.frozenChartArea ?? dims.chartArea;
-  const finalLegend = placeLegend(
-    plan.legendContent,
-    chartArea,
-    options.width,
-    theme,
-    plan.xAxisExtent,
-    dims.effectiveAxisGap
-  );
-  const sizeLegend = plan.sizeLegendContent ? placeSizeLegend(plan.sizeLegendContent, chartArea, theme, finalLegend) : null;
-  const allLegends = [finalLegend, ...sizeLegend ? [sizeLegend] : []];
   let scaleArea = chartArea;
   if (plan.inlineYLabelInset > 0 && plan.inlineYLabelInset < chartArea.width) {
     scaleArea = {
@@ -20599,6 +21459,12 @@ function compileChart(spec, optionsInput) {
   );
   const renderer = getChartRenderer(rendererKey);
   const marks = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme, options.width) : [];
+  if (marks.some((mark) => mark.type === "line" && mark.label?.visible)) {
+    emitSpecWarnings(
+      ["[openchart] Legacy end-of-line labels are deprecated; use endpointLabels."],
+      options.onWarn
+    );
+  }
   applyFillPatterns(marks, chartSpec.markDef, theme);
   const markRenderModeWarnings = [];
   const markRenderMode = resolveMarkRenderMode(
@@ -20623,6 +21489,18 @@ function compileChart(spec, optionsInput) {
     strategy,
     plan.endpointLabelsDemoted
   );
+  const finalLegend = placeLegend(
+    plan.legendContent,
+    // Dimensions reserve both columns; place the legend after the resolved
+    // endpoint column instead of drawing both at the plot's right edge.
+    (plan.legendContent.position === "right" || plan.legendContent.position === "bottom-right") && endpointLabels.entries.length > 0 ? { ...chartArea, width: chartArea.width + ENDPOINT_COLUMN_GAP + endpointLabels.bounds.width } : chartArea,
+    options.width,
+    theme,
+    plan.xAxisExtent,
+    dims.effectiveAxisGap
+  );
+  const sizeLegend = plan.sizeLegendContent ? placeSizeLegend(plan.sizeLegendContent, chartArea, theme, finalLegend) : null;
+  const allLegends = [finalLegend, ...sizeLegend ? [sizeLegend] : []];
   const obstacles = [];
   if (finalLegend.bounds.width > 0) {
     obstacles.push({ ...finalLegend.bounds, kind: "legend" });
@@ -20658,6 +21536,8 @@ function compileChart(spec, optionsInput) {
     svg: { width: dims.total.width, height: dims.total.height },
     measure: annotationMeasure,
     fontFamily: theme.fonts.family,
+    colors: theme.colors,
+    onWarn: (message) => emitSpecWarnings([message], options.onWarn),
     autoThin: chartSpec.autoThin,
     // Hand-placed blocks skip every nudge pass, so the clamp is the only lever
     // that keeps an author's offset from parking a callout on the title.
@@ -20675,24 +21555,28 @@ function compileChart(spec, optionsInput) {
     );
   }
   let footnotes;
-  if (chartSpec.autoThin && annotations.length > 1) {
+  if (chartSpec.autoThin && (annotations.length > 1 || chartSpec.compactAnnotationLimit != null)) {
     const result = thinAnnotations(
       annotations,
       chartSpec.annotations,
       annotationMeasure,
       chartArea,
-      { x: 0, y: 0, width: dims.total.width, height: dims.total.height }
+      { x: 0, y: 0, width: dims.total.width, height: dims.total.height },
+      options.width < 400 && options.height >= 200 ? chartSpec.compactAnnotationLimit : void 0
     );
     annotations = result.annotations;
     if (result.footnotes.length > 0) {
-      footnotes = result.footnotes;
-      const reserve = footnoteBandHeight(footnotes.length, theme);
+      footnotes = wrapAnnotationNotes(
+        result.footnotes,
+        dims.total.width,
+        theme,
+        options.measureText
+      );
+      const reserve = computeNoteBandHeight2(annotationNoteLineCount(footnotes), theme);
       const currentReserve = options.footnoteReserve ?? 0;
       if (!options.frozenChartArea && reserve > currentReserve && (options.footnotePass ?? 0) < MAX_FOOTNOTE_PASSES) {
-        const grow = (spec.chromeLayout ?? options.chromeLayout) === "grow";
-        return compileChart(spec, {
+        return compileChartInternal(spec, {
           ...optionsInput,
-          height: optionsInput.height + (grow ? reserve - currentReserve : 0),
           footnoteReserve: reserve,
           footnotePass: (options.footnotePass ?? 0) + 1
         });
@@ -20705,7 +21589,7 @@ function compileChart(spec, optionsInput) {
     (entry) => ({
       key: entry.seriesKey,
       text: `${entry.seriesKey} \xB7 ${entry.value}`,
-      lines: wrapText3(
+      lines: wrapText4(
         `${entry.seriesKey} \xB7 ${entry.value}`,
         theme.fonts.sizes.small,
         500,
@@ -20729,16 +21613,14 @@ function compileChart(spec, optionsInput) {
     })
   ) : [];
   if (seriesSummary.length) {
-    const reserve = footnoteBandHeight(
-      (footnotes?.length ?? 0) + seriesSummary.reduce((count, entry) => count + entry.lines.length, 0),
+    const reserve = computeNoteBandHeight2(
+      Math.max(noteCapacity, annotationNoteLineCount(footnotes ?? [])) + seriesSummary.reduce((count, entry) => count + entry.lines.length, 0),
       theme
     );
     const previousReserve = options.footnoteReserve ?? 0;
     if (!options.frozenChartArea && reserve > previousReserve && (options.footnotePass ?? 0) < MAX_FOOTNOTE_PASSES) {
-      const grow = (spec.chromeLayout ?? options.chromeLayout) === "grow";
-      return compileChart(spec, {
+      return compileChartInternal(spec, {
         ...optionsInput,
-        height: optionsInput.height + (grow ? reserve - previousReserve : 0),
         footnoteReserve: reserve,
         footnotePass: (options.footnotePass ?? 0) + 1
       });
@@ -20763,8 +21645,16 @@ function compileChart(spec, optionsInput) {
     chartSpec.data
   );
   assignAnimationIndices(marks, resolvedAnimation);
+  const noteBandHeight = Math.max(
+    options.footnoteReserve ?? 0,
+    computeNoteBandHeight2(
+      Math.max(noteCapacity, annotationNoteLineCount(footnotes ?? [])) + seriesSummary.reduce((count, entry) => count + entry.lines.length, 0),
+      theme
+    )
+  );
   const chrome = {
     ...dims.chrome,
+    ...noteBandHeight > 0 ? { noteBandHeight } : {},
     ...footnotes ? { footnotes } : {},
     ...seriesSummary.length ? { seriesSummary } : {}
   };
@@ -20859,7 +21749,8 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
     theme,
     strategy,
     watermark,
-    plan
+    plan,
+    false
   );
   const chartArea = dims.chartArea;
   const finalLegend = placeLegend(
@@ -20872,19 +21763,35 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
   );
   const bottomReservation = plan.xAxisExtent;
   const effectiveColumns = facetDirection === "column" ? facetValues.length : facetChannel.columns;
-  const grid = computeFacetGrid(facetValues, effectiveColumns, chartArea, {
-    left: 0,
-    bottom: bottomReservation
-  });
+  const facetAnnotationMeasure = options.measureText ? (text, font) => options.measureText(text, font.fontSize, font.fontWeight).width : heuristicMeasure;
+  const hasOutsideReferences = chartSpec.annotations.some(
+    (a) => a.type === "refline" && a.labelPlacement === "outside" && !!a.label
+  );
+  const referenceInsets = hasOutsideReferences ? {
+    measure: (width) => referenceLabelReserve(chartSpec.annotations, width, facetAnnotationMeasure),
+    innerAxisWidth: (chartSpec.resolve?.scale?.y ?? (facetDirection === "row" ? "independent" : "shared")) === "independent" ? plan.leftGutter : 0
+  } : void 0;
+  const grid = computeFacetGrid(
+    facetValues,
+    effectiveColumns,
+    chartArea,
+    {
+      left: 0,
+      bottom: bottomReservation
+    },
+    referenceInsets
+  );
   if (!optionsInput.facetHeightGrown && grid.panels.length > 0 && grid.panels[0].area.height < MIN_PANEL_HEIGHT) {
-    const neededChartHeight = facetMinHeight(facetValues.length, grid.columns);
+    const neededChartHeight = grid.minimumHeight ?? facetMinHeight(facetValues.length, grid.columns);
     const heightGrowth = neededChartHeight - chartArea.height;
     if (heightGrowth > 0) {
-      return compileChart(rawSpec, {
+      const grown = compileChartInternal(rawSpec, {
         ...optionsInput,
         height: options.height + heightGrowth,
         facetHeightGrown: true
       });
+      if (grown.chrome.grownHeight !== void 0) grown.chrome.grownHeight += heightGrowth;
+      return grown;
     }
   }
   const resolveConfig = chartSpec.resolve;
@@ -20948,7 +21855,9 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
       data: panelData,
       encoding: panelSpecWithDomains.encoding,
       markType: chartSpec.markType,
-      totalWidth: gridPanel.area.width
+      // Outside-label cells use figure coordinates throughout, including
+      // the tick-label clamp. Keep the legacy path unchanged in 8.x.
+      totalWidth: gridPanel.referenceContainer ? gridPanel.area.x + gridPanel.area.width : gridPanel.area.width
     });
     if (!isRadial) {
       computeGridlines(panelAxes, gridPanel.area);
@@ -20984,22 +21893,31 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
     let panelAnnotations = computeAnnotations(panelSpecWithDomains, {
       scales: panelScales,
       chartArea: gridPanel.area,
+      referenceContainer: gridPanel.referenceContainer,
+      referenceReserve: gridPanel.referenceContainer ? referenceLabelReserve(
+        chartSpec.annotations,
+        gridPanel.referenceContainer.width,
+        facetAnnotationMeasure
+      ) : void 0,
       strategy,
       isDark: theme.isDark,
       obstacles: [],
-      svg: { width: options.width, height: options.height },
+      svg: { width: dims.total.width, height: dims.total.height },
       measure: annotationMeasure,
       fontFamily: theme.fonts.family,
+      colors: theme.colors,
+      onWarn: (message) => emitSpecWarnings([message], options.onWarn),
       autoThin: panelSpecWithDomains.autoThin,
       topBound: dims.chrome.topHeight > 0 ? dims.topPad + dims.chrome.topHeight : void 0
     });
-    if (chartSpec.autoThin && panelAnnotations.length > 1) {
+    if (chartSpec.autoThin && (panelAnnotations.length > 1 || chartSpec.compactAnnotationLimit != null)) {
       const thinned = thinAnnotations(
         panelAnnotations,
         chartSpec.annotations,
         annotationMeasure,
         gridPanel.area,
-        gridPanel.area
+        gridPanel.area,
+        options.width < 400 && options.height >= 200 ? chartSpec.compactAnnotationLimit : void 0
       );
       panelAnnotations = thinned.annotations;
       for (const a of panelAnnotations) {
@@ -21010,6 +21928,8 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
           num = allFootnotes.length + 1;
           footnoteNumberBySpecIndex.set(a.specIndex, num);
           allFootnotes.push({
+            specIndex: a.specIndex,
+            ...a.id !== void 0 ? { id: a.id } : {},
             index: num,
             text: thinned.footnotes[panelIndex - 1]?.text ?? ""
           });
@@ -21034,11 +21954,17 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
       }
     });
   }
+  const wrappedFootnotes = wrapAnnotationNotes(
+    allFootnotes,
+    dims.total.width,
+    theme,
+    options.measureText
+  );
   if (allFootnotes.length > 0 && !options.frozenChartArea) {
-    const reserve = footnoteBandHeight(allFootnotes.length, theme);
+    const reserve = computeNoteBandHeight2(annotationNoteLineCount(wrappedFootnotes), theme);
     const currentReserve = options.footnoteReserve ?? 0;
     if (reserve > currentReserve && (options.footnotePass ?? 0) < MAX_FOOTNOTE_PASSES) {
-      return compileChart(rawSpec, {
+      return compileChartInternal(rawSpec, {
         ...optionsInput,
         footnoteReserve: reserve,
         footnotePass: (options.footnotePass ?? 0) + 1
@@ -21046,6 +21972,12 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
     }
   }
   const tooltipDescriptors = computeTooltipDescriptors(panelChartSpec, allMarks);
+  if (allMarks.some((mark) => mark.type === "line" && mark.label?.visible)) {
+    emitSpecWarnings(
+      ["[openchart] Legacy end-of-line labels are deprecated; use endpointLabels."],
+      options.onWarn
+    );
+  }
   applyFillPatterns(allMarks, chartSpec.markDef, theme);
   const panelCount = facetValues.length;
   const baseAltText = generateAltText(
@@ -21082,7 +22014,14 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
   emitSpecWarnings(facetRenderModeWarnings, options.onWarn);
   return {
     area: chartArea,
-    chrome: allFootnotes.length > 0 ? { ...dims.chrome, footnotes: allFootnotes } : dims.chrome,
+    chrome: {
+      ...dims.chrome,
+      noteBandHeight: Math.max(
+        options.footnoteReserve ?? 0,
+        computeNoteBandHeight2(annotationNoteLineCount(wrappedFootnotes), theme)
+      ),
+      ...allFootnotes.length > 0 ? { footnotes: wrappedFootnotes } : {}
+    },
     metrics: dims.metrics,
     ...dims.seriesSearch ? { seriesSearch: dims.seriesSearch } : {},
     axes: { x: void 0, y: void 0 },
@@ -21102,7 +22041,7 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
       ...chartSpec.a11y?.hidden ? { hidden: true } : {}
     },
     theme,
-    dimensions: { width: options.width, height: options.height },
+    dimensions: { width: dims.total.width, height: dims.total.height },
     animation: resolvedAnimation,
     watermark,
     display: chartSpec.display,
@@ -21125,7 +22064,19 @@ function compileLayer2(spec, options) {
   );
   emitSpecWarnings(sugarWarnings, options.onWarn);
   const resolvedOptions = applySpecSize(expanded, options);
-  return compileLayer(expanded, resolvedOptions, compileChart);
+  const layout = compileLayer(
+    expanded,
+    {
+      ...resolvedOptions,
+      onDiagnostic: options.onDiagnostic ? (diagnostic2) => {
+        if (diagnostic2.code !== "layout.note-capacity") options.onDiagnostic(diagnostic2);
+      } : void 0
+    },
+    compileChartInternal
+  );
+  const diagnostic = noteCapacityDiagnostic(layout);
+  if (diagnostic) options.onDiagnostic?.(diagnostic);
+  return layout;
 }
 function compileTable(spec, options) {
   const { spec: normalized, warnings: normalizeWarnings } = compile(spec);
@@ -21135,7 +22086,8 @@ function compileTable(spec, options) {
     throw new Error(`compileTable received a non-table spec. Use compileChart instead.`);
   }
   const tableSpec = normalized;
-  const mergedThemeConfig = options.theme ? { ...tableSpec.theme, ...options.theme } : tableSpec.theme;
+  emitThemeWarnings(options.theme, options.onWarn);
+  const mergedThemeConfig = mergeThemeConfig6(tableSpec.theme, options.theme);
   let theme = resolveTheme7(mergedThemeConfig);
   if (options.darkMode) {
     theme = adaptTheme6(theme);
@@ -21160,6 +22112,58 @@ function compileBarList2(spec, options) {
   return compileBarList(spec, options);
 }
 
+// src/annotations/interpolate.ts
+function interpolateAnnotationGeometry(before, after, t) {
+  if (t >= 1) return structuredClone(after);
+  const result = structuredClone(after);
+  const point = (a, b) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t
+  });
+  if (before.label && result.label) {
+    const pos = point(before.label, result.label);
+    const dx = pos.x - result.label.x;
+    const dy = pos.y - result.label.y;
+    result.label.x = pos.x;
+    result.label.y = pos.y;
+    if (result.label.bounds) {
+      result.label.bounds.x += dx;
+      result.label.bounds.y += dy;
+    }
+    if (result.bounds) {
+      result.bounds.x += dx;
+      result.bounds.y += dy;
+    }
+    if (result.subtitle) {
+      result.subtitle.x += dx;
+      result.subtitle.y += dy;
+    }
+  }
+  if (before.dot && result.dot) Object.assign(result.dot, point(before.dot, result.dot));
+  if (before.line && result.line) {
+    result.line.start = point(before.line.start, result.line.start);
+    result.line.end = point(before.line.end, result.line.end);
+  }
+  if (before.rect && result.rect) {
+    const rect = result.rect;
+    Object.assign(rect, point(before.rect, rect));
+    rect.width = before.rect.width + (rect.width - before.rect.width) * t;
+    rect.height = before.rect.height + (rect.height - before.rect.height) * t;
+  }
+  const connector = result.label?.connector;
+  if (connector?.endpoint && result.bounds) {
+    const start = before.label?.connector?.endpoint ?? before.dot ?? connector.endpoint;
+    connector.endpoint = point(start, connector.endpoint);
+    result.label.connector = refreshConnector(
+      connector,
+      result.bounds,
+      markerClearance(result.dot),
+      true
+    );
+  }
+  return result;
+}
+
 // src/design/patch.ts
 var unsafe = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
 function applySpecPatch(spec, patch) {
@@ -21329,6 +22333,246 @@ function recommendCompositions(data, question, roles) {
   }
   return { recommendations: recommendations.slice(0, 3), missingRoles: [] };
 }
+
+// src/migration/v8.ts
+import { legacyEditorial } from "@opendata-ai/openchart-core";
+var node = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+var escapePointer = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
+function migrateSpecV8(input) {
+  const repairs = [];
+  const clone = (value) => Array.isArray(value) ? value.map(clone) : node(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) ? Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, clone(child)])
+  ) : value;
+  const spec = clone(input);
+  function visit(current, path, inherited = {}) {
+    function replace(owner, key, value, at, reason) {
+      repairs.push({
+        path: `${at}/${escapePointer(key)}`,
+        from: clone(owner[key]),
+        to: clone(value),
+        reason
+      });
+      if (value === void 0) delete owner[key];
+      else owner[key] = value;
+    }
+    const rewrite = (key, value, reason) => replace(current, key, value, path, reason);
+    if ("darkMode" in current)
+      rewrite("darkMode", void 0, "Spec darkMode has no effect; use the mount option.");
+    if (current.type === "table" && "compact" in current) {
+      if (current.density === void 0)
+        rewrite("density", current.compact ? "condensed" : "regular", "Use table density.");
+      rewrite("compact", void 0, "Replaced by density.");
+    }
+    const theme = node(current.theme);
+    const chrome = node(theme?.chrome);
+    if (chrome)
+      for (const [key, value] of Object.entries(chrome)) {
+        if (typeof value === "string")
+          replace(
+            chrome,
+            key,
+            { color: value },
+            `${path}/theme/chrome`,
+            "Use a chrome color object."
+          );
+      }
+    if (current.animation === "legacy")
+      rewrite("animation", true, "Omitting the preset retains v8 animation.");
+    const animation = node(current.animation);
+    if (animation?.preset === "legacy")
+      replace(animation, "preset", void 0, `${path}/animation`, "Omit the legacy preset.");
+    const mark = node(current.mark);
+    if (mark && "render" in mark)
+      replace(mark, "render", void 0, `${path}/mark`, "Use the renderer mount option.");
+    const markType = typeof current.mark === "string" ? current.mark : mark?.type;
+    const encoding = node(current.encoding);
+    if (encoding) {
+      for (const key of ["radius", "shape", "href", "order"]) {
+        if (key in encoding)
+          replace(
+            encoding,
+            key,
+            void 0,
+            `${path}/encoding`,
+            "This channel has no rendering effect."
+          );
+      }
+      if (["arc", "waffle", "parliament"].includes(String(markType)) && "y" in encoding) {
+        if (encoding.theta === void 0)
+          replace(
+            encoding,
+            "theta",
+            encoding.y,
+            `${path}/encoding`,
+            "Use theta for angular values."
+          );
+        replace(encoding, "y", void 0, `${path}/encoding`, "Replaced by theta.");
+      }
+    }
+    if (["sankey", "map", "barlist"].includes(String(current.type)) && typeof current.valueFormat === "string") {
+      const key = current.type === "map" ? "color" : "value";
+      const enc = node(current.encoding) ?? {};
+      const channel = node(enc[key]);
+      if (channel) {
+        if (channel.format === void 0)
+          replace(
+            channel,
+            "format",
+            current.valueFormat,
+            `${path}/encoding/${key}`,
+            "Use channel format."
+          );
+        rewrite("valueFormat", void 0, "Replaced by channel format.");
+      }
+    }
+    if (Array.isArray(current.annotations))
+      for (const [index, value] of current.annotations.entries()) {
+        const annotation = node(value);
+        if (annotation?.type === "rule")
+          replace(annotation, "type", "refline", `${path}/annotations/${index}`, "Use refline.");
+      }
+    if (Array.isArray(current.annotations))
+      for (const [index, value] of current.annotations.entries()) {
+        const annotation = node(value);
+        if (!annotation) continue;
+        const at = `${path}/annotations/${index}`;
+        const setDefault = (key, value2) => {
+          if (annotation[key] === void 0)
+            replace(annotation, key, value2, at, "Preserve the v8 annotation default.");
+        };
+        if (annotation.type === "text") {
+          setDefault("maxWidth", null);
+          if (annotation.subtitle) {
+            setDefault("fontWeight", 700);
+            setDefault(
+              "subtitleFontSize",
+              Math.round(
+                (typeof annotation.fontSize === "number" ? annotation.fontSize : 13) * 0.85
+              )
+            );
+          }
+          if (annotation.connector === "curve")
+            replace(
+              annotation,
+              "connector",
+              { type: "curve", arrow: true },
+              at,
+              "Preserve the v8 curve arrow."
+            );
+          const connector = node(annotation.connector);
+          if (connector?.type === "curve" && connector.arrow === void 0)
+            replace(connector, "arrow", true, `${at}/connector`, "Preserve the v8 curve arrow.");
+        }
+        if (annotation.type === "refline" && annotation.label && annotation.labelAnchor === void 0 && annotation.labelPlacement === void 0) {
+          setDefault("labelAnchor", annotation.y !== void 0 ? "top" : "left");
+        }
+      }
+    const isChart = current.mark !== void 0 || Array.isArray(current.layer);
+    const isLayer = Array.isArray(current.layer);
+    if (isChart && !isLayer && current.chromeLayout === void 0)
+      rewrite("chromeLayout", "subtract", "Preserve the v8 fixed figure budget.");
+    if (isChart && (!isLayer || current.responsive !== void 0 || typeof current.width === "number" && typeof current.height === "number")) {
+      const responsive = current.responsive;
+      if (responsive !== false) {
+        if (responsive === void 0 && typeof current.width === "number" && typeof current.height === "number")
+          rewrite("responsive", false, "Preserve the fixed-size responsive opt-out.");
+        else if (node(responsive)?.compactAnnotationLimit === void 0)
+          rewrite(
+            "responsive",
+            { ...node(responsive), compactAnnotationLimit: null },
+            "Preserve unlimited v8 compact annotations."
+          );
+      }
+    }
+    if (!isLayer && (isChart || current.type !== void 0) && inherited.theme === void 0 || current.theme !== void 0) {
+      const oldTheme = { ...node(current.theme) };
+      const fonts = node(oldTheme.fonts) ?? {};
+      const sizes = node(fonts.sizes) ?? {};
+      const chromeDefaults = node(oldTheme.chrome) ?? {};
+      const newSizes = { ...sizes };
+      for (const [key, value] of Object.entries(legacyEditorial.fonts.sizes)) {
+        const matching = key === "small" ? ["source", "byline", "footer"] : [key];
+        if (newSizes[key] === void 0 && !matching.some((name) => node(chromeDefaults[name])?.fontSize !== void 0))
+          newSizes[key] = value;
+      }
+      const newChrome = { ...chromeDefaults };
+      for (const key of ["byline", "source", "footer"]) {
+        const entry = node(newChrome[key]) ?? {};
+        if (entry.fontSize === void 0)
+          newChrome[key] = { ...entry, fontSize: sizes.small ?? 11 };
+      }
+      const materialized = { ...oldTheme, fonts: { ...fonts, sizes: newSizes }, chrome: newChrome };
+      if (JSON.stringify(materialized) !== JSON.stringify(current.theme))
+        rewrite(
+          "theme",
+          materialized,
+          "Preserve v8 typography without overriding authored chrome sizes."
+        );
+    }
+    const data = current.data ?? inherited.data;
+    const effectiveEncoding = { ...node(inherited.encoding), ...encoding };
+    const labels = node(current.labels);
+    const endpoint = current.endpointLabels ?? inherited.endpointLabels;
+    let legacyLabels = false;
+    const effective = {
+      ...inherited,
+      ...current,
+      data: data ?? [],
+      encoding: effectiveEncoding
+    };
+    const layerSpec = effective;
+    const leaves = Array.isArray(current.layer) ? flattenLayers(layerSpec) : [];
+    const migrationSources = leaves.length ? layerSpec.resolve?.scale?.y === "independent" ? leaves.map((leaf) => buildPrimarySpec([leaf], layerSpec)) : [buildPrimarySpec(leaves, layerSpec)] : [effective];
+    legacyLabels = migrationSources.some((migrationSource) => {
+      const sourceMark = typeof migrationSource.mark === "string" ? migrationSource.mark : node(migrationSource.mark)?.type;
+      if (!["line", "area"].includes(String(sourceMark))) return false;
+      const normalized = normalizeSpec(
+        expandSpecSugar(migrationSource)
+      );
+      return resolveSuppression(normalized, {
+        seriesCount: countColorSeries(normalized),
+        labelsHiddenByStrategy: false,
+        labelsDensityNone: normalized.labels.density === "none"
+      }).showEndOfLineLabels;
+    });
+    if (legacyLabels)
+      rewrite(
+        "endpointLabels",
+        { content: "label", showMarker: false },
+        "Replace legacy end-of-line labels with the endpoint column; label positions may change."
+      );
+    const offsets = node(labels?.offsets);
+    if (labels && offsets) {
+      for (const key of Object.keys(offsets))
+        replace(
+          offsets,
+          key,
+          void 0,
+          `${path}/labels/offsets`,
+          "Manual legacy-label offset cannot be represented by endpoint labels."
+        );
+      delete labels.offsets;
+    }
+    if (Array.isArray(current.layer))
+      current.layer.forEach((child, index) => {
+        const childNode = node(child);
+        if (childNode)
+          visit(childNode, `${path}/layer/${index}`, {
+            data,
+            theme: current.theme ?? inherited.theme,
+            responsive: current.responsive ?? inherited.responsive,
+            chromeLayout: current.chromeLayout ?? inherited.chromeLayout,
+            encoding: effectiveEncoding,
+            endpointLabels: current.endpointLabels ?? endpoint,
+            legend: current.legend ?? inherited.legend,
+            labels: current.labels ?? inherited.labels
+          });
+      });
+  }
+  const root = node(spec);
+  if (root) visit(root, "");
+  return { spec, repairs };
+}
 export {
   ARROWHEAD_LENGTH,
   AUTO_CANVAS_THRESHOLD,
@@ -21340,6 +22584,7 @@ export {
   MAX_3D_NODES,
   UPDATE_DEFAULTS,
   applySpecPatch,
+  automaticControlPoint,
   buildArcPath,
   buildAreaPath,
   buildEdgeTooltip,
@@ -21357,20 +22602,28 @@ export {
   compileTable,
   compileTileMap2 as compileTileMap,
   computeArrowheadPoints,
+  createAnnotationEditContext,
   dedupeKeys,
   diagnoseChart,
   evaluatePredicate,
   facetMinHeight,
   getChartRenderer,
   heuristicMeasure,
+  interpolateAnnotationGeometry,
+  inverseLabelPlacement,
   isConditionalValueDef,
   legendGap,
   linkedEntityKeys,
+  migrateSpecV8,
   normalizeSpec,
   observationKey,
   parseAnnotationSpans,
+  previewAnnotationMove,
+  previewConnectorBend,
+  previewConnectorOffset,
   recommendCompositions,
   reconcileReaderSelection,
+  refreshConnector,
   registerChartRenderer,
   resolveAnimation,
   resolveConditionalValue,