graphein 0.17.0 → 0.18.0

package/dist/index.js

@@ -353,7 +353,7 @@ function clampValue(value, min, max) {
 function linearScale(opts) {
   const domain = [opts.domain[0], opts.domain[1]];
   const range = [opts.range[0], opts.range[1]];
-  const clamp11 = opts.clamp === true;
+  const clamp16 = opts.clamp === true;
   const scale = {
     get domain() {
       return domain;
@@ -368,7 +368,7 @@ function linearScale(opts) {
         return r0;
       }
       const mapped = r0 + (value - d0) / (d1 - d0) * (r1 - r0);
-      return clamp11 ? clampValue(mapped, Math.min(r0, r1), Math.max(r0, r1)) : mapped;
+      return clamp16 ? clampValue(mapped, Math.min(r0, r1), Math.max(r0, r1)) : mapped;
     },
     invert(pixel) {
       const [d0, d1] = domain;
@@ -376,7 +376,7 @@ function linearScale(opts) {
       if (r0 === r1) {
         return d0;
       }
-      const input = clamp11 ? clampValue(pixel, Math.min(r0, r1), Math.max(r0, r1)) : pixel;
+      const input = clamp16 ? clampValue(pixel, Math.min(r0, r1), Math.max(r0, r1)) : pixel;
       return d0 + (input - r0) / (r1 - r0) * (d1 - d0);
     },
     ticks(count = 10) {
@@ -388,10 +388,10 @@ function linearScale(opts) {
       return (value) => formatNumber(value, precision);
     },
     nice(count = 10) {
-      return linearScale({ domain: niceDomain(domain[0], domain[1], count), range, clamp: clamp11 });
+      return linearScale({ domain: niceDomain(domain[0], domain[1], count), range, clamp: clamp16 });
     },
     copy() {
-      return linearScale({ domain, range, clamp: clamp11 });
+      return linearScale({ domain, range, clamp: clamp16 });
     }
   };
   return scale;
@@ -447,7 +447,7 @@ function logScale(opts) {
   const domain = [opts.domain[0], opts.domain[1]];
   const range = [opts.range[0], opts.range[1]];
   const base = opts.base ?? 10;
-  const clamp11 = opts.clamp === true;
+  const clamp16 = opts.clamp === true;
   assertDomain(domain, base);
   const sign2 = domain[0] < 0 ? -1 : 1;
   const transformedDomain = [
@@ -466,17 +466,17 @@ function logScale(opts) {
       const [r0, r1] = range;
       if (!Number.isFinite(value) || value * sign2 <= 0) return NaN;
       if (d0 === d1) {
-        return clamp11 ? clampValue2(r0, Math.min(r0, r1), Math.max(r0, r1)) : r0;
+        return clamp16 ? clampValue2(r0, Math.min(r0, r1), Math.max(r0, r1)) : r0;
       }
       const transformed = transform(value, sign2, base);
       const mapped = r0 + (transformed - d0) / (d1 - d0) * (r1 - r0);
-      return clamp11 ? clampValue2(mapped, Math.min(r0, r1), Math.max(r0, r1)) : mapped;
+      return clamp16 ? clampValue2(mapped, Math.min(r0, r1), Math.max(r0, r1)) : mapped;
     },
     invert(pixel) {
       const [d0, d1] = transformedDomain;
       const [r0, r1] = range;
       if (d0 === d1) return domain[0];
-      const input = clamp11 ? clampValue2(pixel, Math.min(r0, r1), Math.max(r0, r1)) : pixel;
+      const input = clamp16 ? clampValue2(pixel, Math.min(r0, r1), Math.max(r0, r1)) : pixel;
       return untransform(d0 + (input - r0) / (r1 - r0) * (d1 - d0), sign2, base);
     },
     ticks() {
@@ -486,10 +486,10 @@ function logScale(opts) {
       return (value) => formatNumber(value, 12);
     },
     nice() {
-      return logScale({ domain: niceLogDomain(domain, base), range, base, clamp: clamp11 });
+      return logScale({ domain: niceLogDomain(domain, base), range, base, clamp: clamp16 });
     },
     copy() {
-      return logScale({ domain, range, base, clamp: clamp11 });
+      return logScale({ domain, range, base, clamp: clamp16 });
     }
   };
   return scale;
@@ -505,7 +505,7 @@ function clampValue3(value, min, max) {
 function timeScale(opts) {
   const domain = [toMillis(opts.domain[0]), toMillis(opts.domain[1])];
   const range = [opts.range[0], opts.range[1]];
-  const clamp11 = opts.clamp === true;
+  const clamp16 = opts.clamp === true;
   const scale = {
     get domain() {
       return domain;
@@ -520,7 +520,7 @@ function timeScale(opts) {
         return r0;
       }
       const mapped = r0 + (value - d0) / (d1 - d0) * (r1 - r0);
-      return clamp11 ? clampValue3(mapped, Math.min(r0, r1), Math.max(r0, r1)) : mapped;
+      return clamp16 ? clampValue3(mapped, Math.min(r0, r1), Math.max(r0, r1)) : mapped;
     },
     invert(pixel) {
       const [d0, d1] = domain;
@@ -528,7 +528,7 @@ function timeScale(opts) {
       if (r0 === r1) {
         return d0;
       }
-      const input = clamp11 ? clampValue3(pixel, Math.min(r0, r1), Math.max(r0, r1)) : pixel;
+      const input = clamp16 ? clampValue3(pixel, Math.min(r0, r1), Math.max(r0, r1)) : pixel;
       return d0 + (input - r0) / (r1 - r0) * (d1 - d0);
     },
     ticks(count = 10) {
@@ -540,12 +540,12 @@ function timeScale(opts) {
     nice(count = 10) {
       const values = timeTicks(domain[0], domain[1], count);
       if (values.length === 0) {
-        return timeScale({ domain, range, clamp: clamp11 });
+        return timeScale({ domain, range, clamp: clamp16 });
       }
-      return timeScale({ domain: [values[0], values[values.length - 1]], range, clamp: clamp11 });
+      return timeScale({ domain: [values[0], values[values.length - 1]], range, clamp: clamp16 });
     },
     copy() {
-      return timeScale({ domain, range, clamp: clamp11 });
+      return timeScale({ domain, range, clamp: clamp16 });
     }
   };
   return scale;
@@ -736,6 +736,28 @@ function interpolateOklab(a, b) {
   };
 }
 
+// src/color/contrast.ts
+var WHITE = { r: 255, g: 255, b: 255, a: 1 };
+var BLACK = { r: 0, g: 0, b: 0, a: 1 };
+function relativeLuminance(c) {
+  const r = srgbToLinear(c.r / 255);
+  const g = srgbToLinear(c.g / 255);
+  const b = srgbToLinear(c.b / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const lighter = Math.max(la, lb);
+  const darker = Math.min(la, lb);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function readableTextColor(bg, options = {}) {
+  const light = options.light ?? WHITE;
+  const dark = options.dark ?? BLACK;
+  return contrastRatio(bg, light) >= contrastRatio(bg, dark) ? light : dark;
+}
+
 // src/color/palettes.ts
 var CATEGORICAL = {
   graphein: [
@@ -781,6 +803,25 @@ var must = (hex) => {
   if (!c) throw new Error(`Graphein: invalid palette color ${hex}`);
   return c;
 };
+function candidateWithChroma(color, lightness, chroma) {
+  const lch = oklabToOklch(rgbToOklab(color));
+  return oklabToRgb(oklchToOklab({ L: lightness, C: chroma, h: lch.h }), color.a);
+}
+function adaptPaletteForDarkBackground(palette, background = "#0b1220", minContrast = 3) {
+  const bg = parseColor(background);
+  if (!bg) return [...palette];
+  return palette.map((color) => {
+    const parsed = parseColor(color);
+    if (!parsed) return color;
+    const lch = oklabToOklch(rgbToOklab(parsed));
+    const lightness = Math.max(lch.L, 0.68);
+    for (let chroma = lch.C; chroma >= 0; chroma -= 2e-3) {
+      const candidate = candidateWithChroma(parsed, lightness, chroma);
+      if (contrastRatio(candidate, bg) >= minContrast) return toHex(candidate);
+    }
+    return toHex(candidateWithChroma(parsed, lightness, 0));
+  });
+}
 function rampFromStops(stops) {
   const colors = stops.map(must);
   if (colors.length === 1) return () => ({ ...colors[0] });
@@ -866,28 +907,6 @@ function ordinalColorScale(opts) {
   };
 }
 
-// src/color/contrast.ts
-var WHITE = { r: 255, g: 255, b: 255, a: 1 };
-var BLACK = { r: 0, g: 0, b: 0, a: 1 };
-function relativeLuminance(c) {
-  const r = srgbToLinear(c.r / 255);
-  const g = srgbToLinear(c.g / 255);
-  const b = srgbToLinear(c.b / 255);
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-function contrastRatio(a, b) {
-  const la = relativeLuminance(a);
-  const lb = relativeLuminance(b);
-  const lighter = Math.max(la, lb);
-  const darker = Math.min(la, lb);
-  return (lighter + 0.05) / (darker + 0.05);
-}
-function readableTextColor(bg, options = {}) {
-  const light = options.light ?? WHITE;
-  const dark = options.dark ?? BLACK;
-  return contrastRatio(bg, light) >= contrastRatio(bg, dark) ? light : dark;
-}
-
 // src/shape/curves.ts
 var sign = (value) => value < 0 ? -1 : value > 0 ? 1 : 0;
 function curveLinear(points, sink) {
@@ -1865,8 +1884,8 @@ function chartTitleText(spec) {
   const t = spec.title;
   if (typeof t === "string") return t.trim() || void 0;
   if (t && typeof t === "object") {
-    const text = t.text;
-    return typeof text === "string" && text.trim() ? text.trim() : void 0;
+    const text2 = t.text;
+    return typeof text2 === "string" && text2.trim() ? text2.trim() : void 0;
   }
   return void 0;
 }
@@ -5411,8 +5430,8 @@ function profileColumns(data) {
     cardinality: uniqueValues(data, field).length
   }));
 }
-function title(text) {
-  return text.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().replace(/\b\w/g, (m) => m.toUpperCase());
+function title(text2) {
+  return text2.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().replace(/\b\w/g, (m) => m.toUpperCase());
 }
 function fieldDef2(profile) {
   return { field: profile.field, type: profile.type };
@@ -5431,6 +5450,77 @@ function pushValid(candidates, candidate, intent) {
 function firstLowCardNominal(profiles, exclude = /* @__PURE__ */ new Set()) {
   return profiles.find((p) => p.type === "nominal" && p.cardinality <= 12 && !exclude.has(p.field));
 }
+function numericValues(data, field) {
+  return data.map((row) => Number(row[field])).filter((value) => Number.isFinite(value));
+}
+function stringValues(data, field) {
+  return data.map((row) => row[field]).filter((value) => value != null && value !== "").map((value) => String(value));
+}
+function hasPositiveValues(data, field) {
+  const values = numericValues(data, field);
+  return values.length > 0 && values.every((value) => value > 0);
+}
+function fieldNameMatches(field, words) {
+  const normalized2 = field.toLowerCase();
+  return words.some((word) => normalized2.includes(word));
+}
+function hasConversionVocabulary(values) {
+  const vocabulary = [
+    "visit",
+    "lead",
+    "signup",
+    "sign up",
+    "register",
+    "activate",
+    "subscribe",
+    "convert",
+    "purchase",
+    "checkout",
+    "renew",
+    "trial",
+    "demo",
+    "onboard"
+  ];
+  return values.some((value) => {
+    const normalized2 = value.toLowerCase();
+    return vocabulary.some((word) => normalized2.includes(word));
+  });
+}
+function isNearMonotoneDecreasing(values) {
+  if (values.length < 3) return false;
+  let decreases = 0;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i] <= values[i - 1] * 1.05) decreases++;
+  }
+  return decreases / (values.length - 1) >= 0.8;
+}
+function distinctDates(data, field) {
+  return uniqueValues(data, field).map((value) => {
+    if (value instanceof Date) return value;
+    if (typeof value === "string" || typeof value === "number") return new Date(value);
+    return null;
+  }).filter((value) => value instanceof Date && !Number.isNaN(value.getTime())).sort((a, b) => a.getTime() - b.getTime());
+}
+function groupsWithAllValues(data, groupField, valueField4, expected) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of data) {
+    const group = row[groupField];
+    const value = row[valueField4];
+    if (group == null || value == null) continue;
+    const key = String(group);
+    const values = groups.get(key) ?? /* @__PURE__ */ new Set();
+    values.add(String(value));
+    groups.set(key, values);
+  }
+  let complete = 0;
+  for (const values of groups.values()) {
+    if ([...expected].every((value) => values.has(value))) complete++;
+  }
+  return complete;
+}
+function profileByName(profiles, words) {
+  return profiles.find((profile) => fieldNameMatches(profile.field, words));
+}
 function recommendChart(data, opts = {}) {
   if (!Array.isArray(data) || data.length === 0) return [];
   const profiles = profileColumns(data);
@@ -5440,7 +5530,285 @@ function recommendChart(data, opts = {}) {
   const lowNominal = nominal.filter((p) => p.cardinality <= 12);
   const manyNominal = nominal.filter((p) => p.cardinality > 12);
   const candidates = [];
-  const measure = quantitative[0];
+  const measure = quantitative.find((p) => p.cardinality > 2) ?? quantitative[0];
+  if (measure) {
+    const stage = profiles.find(
+      (p) => (p.type === "nominal" || p.type === "ordinal") && p.cardinality >= 3 && p.cardinality <= 12 && p.cardinality === data.length
+    );
+    if (stage && hasPositiveValues(data, measure.field)) {
+      const values = numericValues(data, measure.field);
+      const stages = stringValues(data, stage.field);
+      const stageLike = fieldNameMatches(stage.field, ["stage", "step", "funnel", "phase", "status"]);
+      const conversionLike = hasConversionVocabulary(stages);
+      if (isNearMonotoneDecreasing(values) && (stageLike || conversionLike)) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "funnel",
+              data,
+              encoding: { stage: fieldDef2(stage), value: fieldDef2(measure) },
+              title: `${title(measure.field)} funnel by ${title(stage.field)}`,
+              percent: "first"
+            },
+            score: 0.88,
+            family: "composition",
+            rationale: `${title(stage.field)} looks like ordered funnel stages and ${title(measure.field)} mostly decreases, so a funnel shows conversion drop-off.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
+  if (measure) {
+    const stage = profiles.find(
+      (p) => (p.type === "nominal" || p.type === "ordinal") && p.cardinality >= 3 && p.cardinality <= 20 && p.cardinality === data.length
+    );
+    if (stage) {
+      const values = numericValues(data, measure.field);
+      const hasIncrease = values.some((value) => value > 0);
+      const hasDecrease = values.some((value) => value < 0);
+      if (values.length === data.length && hasIncrease && hasDecrease) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "waterfall",
+              data,
+              encoding: { stage: fieldDef2(stage), value: fieldDef2(measure) },
+              title: `${title(measure.field)} bridge by ${title(stage.field)}`,
+              showTotal: true
+            },
+            score: 0.87,
+            family: "comparison",
+            rationale: `${title(measure.field)} contains signed positive and negative steps, so a waterfall shows how each ${title(stage.field)} changes the running total.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
+  if (nominal.length >= 2 && measure && hasPositiveValues(data, measure.field)) {
+    const source = profileByName(nominal, ["source", "from", "origin", "upstream"]) ?? nominal.find((profile) => profile.cardinality >= 2 && profile.cardinality <= 30);
+    const target = profileByName(nominal.filter((profile) => profile.field !== source?.field), [
+      "target",
+      "to",
+      "destination",
+      "downstream"
+    ]) ?? nominal.find((profile) => profile.field !== source?.field && profile.cardinality >= 2 && profile.cardinality <= 30);
+    if (source && target) {
+      const sourceNames = new Set(stringValues(data, source.field));
+      const targetNames = new Set(stringValues(data, target.field));
+      const sharedNodes = [...sourceNames].filter((value) => targetNames.has(value)).length;
+      const namedFlow = fieldNameMatches(source.field, ["source", "from", "origin", "upstream"]) || fieldNameMatches(target.field, ["target", "to", "destination", "downstream"]);
+      if (namedFlow || sharedNodes > 0) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "sankey",
+              data,
+              encoding: { source: fieldDef2(source), target: fieldDef2(target), value: fieldDef2(measure) },
+              title: `${title(measure.field)} flow from ${title(source.field)} to ${title(target.field)}`
+            },
+            score: 0.82,
+            family: "relationship",
+            rationale: `${title(source.field)} and ${title(target.field)} form source and target entities with positive ${title(measure.field)}, so a sankey shows flow magnitude.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
+  if (measure && hasPositiveValues(data, measure.field)) {
+    const category = nominal.find((profile) => profile.cardinality > 7);
+    if (category) {
+      const group = firstLowCardNominal(profiles, /* @__PURE__ */ new Set([category.field, measure.field]));
+      pushValid(
+        candidates,
+        {
+          spec: {
+            type: "treemap",
+            data,
+            encoding: {
+              category: fieldDef2(category),
+              value: fieldDef2(measure),
+              ...group ? { group: fieldDef2(group) } : {}
+            },
+            title: `${title(measure.field)} by ${title(category.field)}`
+          },
+          score: 0.7,
+          family: "composition",
+          rationale: `${title(category.field)} has ${category.cardinality} categories, too many for a clear pie, so a treemap shows part-to-whole area by ${title(measure.field)}.`
+        },
+        opts.intent
+      );
+    }
+  }
+  if (measure) {
+    const category = lowNominal.find((profile) => {
+      const counts = /* @__PURE__ */ new Map();
+      for (const row of data) {
+        const value = row[profile.field];
+        if (value == null) continue;
+        const key = String(value);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+      }
+      return counts.size >= 2 && [...counts.values()].every((count) => count >= 5);
+    });
+    if (category) {
+      pushValid(
+        candidates,
+        {
+          spec: {
+            type: "box",
+            data,
+            encoding: { x: fieldDef2(category), y: fieldDef2(measure) },
+            title: `${title(measure.field)} distribution by ${title(category.field)}`
+          },
+          score: 0.81,
+          family: "distribution",
+          rationale: `${title(category.field)} repeats with many ${title(measure.field)} observations per category, so a box plot summarizes spread and outliers.`
+        },
+        opts.intent
+      );
+    }
+  }
+  if (measure) {
+    const date = profiles.find((profile) => profile.type === "temporal");
+    if (date) {
+      const dates = distinctDates(data, date.field);
+      const spanDays = dates.length > 1 ? (dates[dates.length - 1].getTime() - dates[0].getTime()) / 864e5 : 0;
+      const density = spanDays > 0 ? dates.length / spanDays : 0;
+      if (dates.length >= 180 && spanDays >= 300 && density >= 0.45) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "calendarHeatmap",
+              data,
+              encoding: { date: fieldDef2(date), color: fieldDef2(measure) },
+              title: `${title(measure.field)} by day`
+            },
+            score: 0.72,
+            family: "density",
+            rationale: `${title(date.field)} is daily temporal data spanning about a year, so a calendar heatmap shows day-by-day ${title(measure.field)} intensity.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
+  if (measure) {
+    const x = profiles.find(
+      (profile) => (profile.type === "temporal" || profile.type === "nominal" || profile.type === "ordinal") && profile.cardinality === 2
+    );
+    const series = nominal.find((profile) => profile.field !== x?.field && profile.cardinality >= 2);
+    if (x && series) {
+      const xValues = new Set(stringValues(data, x.field));
+      if (groupsWithAllValues(data, series.field, x.field, xValues) >= 2) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "slope",
+              data,
+              encoding: { x: fieldDef2(x), y: fieldDef2(measure), series: fieldDef2(series) },
+              title: `${title(measure.field)} change by ${title(series.field)}`,
+              colorByChange: true
+            },
+            score: 0.79,
+            family: "trend",
+            rationale: `${title(x.field)} has exactly two positions for each ${title(series.field)}, so a slope chart emphasizes before-and-after change in ${title(measure.field)}.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
+  if (measure && nominal.length >= 1) {
+    const group = profiles.find((profile) => profile.field !== measure.field && profile.cardinality === 2);
+    const category = nominal.find((profile) => profile.field !== group?.field && profile.cardinality >= 2);
+    if (group && category) {
+      const groupValues = new Set(stringValues(data, group.field));
+      if (groupsWithAllValues(data, category.field, group.field, groupValues) >= 2) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "dumbbell",
+              data,
+              encoding: { category: fieldDef2(category), value: fieldDef2(measure), group: fieldDef2(group) },
+              title: `${title(measure.field)} gap by ${title(category.field)}`,
+              sort: "gap"
+            },
+            score: 0.78,
+            family: "comparison",
+            rationale: `${title(group.field)} has exactly two groups within each ${title(category.field)}, so a dumbbell chart makes the ${title(measure.field)} gap easy to compare.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
+  if (data.length === 1 && quantitative.length >= 2) {
+    const value = profileByName(quantitative, ["value", "actual", "current", "sales", "revenue"]) ?? quantitative[0];
+    const target = profileByName(
+      quantitative.filter((profile) => profile.field !== value.field),
+      ["target", "goal", "budget", "plan", "quota"]
+    );
+    const max = profileByName(
+      quantitative.filter((profile) => profile.field !== value.field && profile.field !== target?.field),
+      ["max", "total", "limit", "capacity"]
+    );
+    const valueNumber = numericValues(data, value.field)[0];
+    const targetNumber = target ? numericValues(data, target.field)[0] : void 0;
+    const maxNumber = max ? numericValues(data, max.field)[0] : void 0;
+    if (target && Number.isFinite(targetNumber)) {
+      pushValid(
+        candidates,
+        {
+          spec: {
+            type: "bullet",
+            data,
+            value: { field: value.field },
+            target: { field: target.field },
+            max: Number.isFinite(maxNumber) ? maxNumber : void 0,
+            label: title(value.field),
+            title: `${title(value.field)} vs ${title(target.field)}`
+          },
+          score: 0.86,
+          family: "value",
+          rationale: `${title(value.field)} is a single value with ${title(target.field)} as a target, so a bullet graph shows compact KPI attainment.`
+        },
+        opts.intent
+      );
+    }
+    if ((max || target) && typeof valueNumber === "number" && Number.isFinite(valueNumber)) {
+      const numericTarget = typeof targetNumber === "number" && Number.isFinite(targetNumber) ? targetNumber : valueNumber;
+      const gaugeMax = typeof maxNumber === "number" && Number.isFinite(maxNumber) ? maxNumber : Math.max(valueNumber, numericTarget) * 1.2;
+      if (gaugeMax > 0 && gaugeMax > valueNumber) {
+        pushValid(
+          candidates,
+          {
+            spec: {
+              type: "gauge",
+              data,
+              value: { field: value.field },
+              max: gaugeMax,
+              target: target ? { field: target.field } : void 0,
+              label: title(value.field),
+              title: `${title(value.field)} attainment`
+            },
+            score: 0.84,
+            family: "value",
+            rationale: `${title(value.field)} is a single value against ${target ? title(target.field) : title(max?.field ?? "Maximum")}, so a gauge shows progress on a bounded scale.`
+          },
+          opts.intent
+        );
+      }
+    }
+  }
   if (ordered.length > 0 && measure) {
     const x = ordered[0];
     const encoding = { x: fieldDef2(x), y: fieldDef2(measure) };
@@ -5687,85 +6055,56 @@ var CanvasLayer = class {
   }
 };
 
-// src/render/surface.ts
-var Surface = class {
-  constructor(container) {
-    __publicField(this, "container");
-    __publicField(this, "root");
-    __publicField(this, "marks");
-    __publicField(this, "interaction");
-    __publicField(this, "overlay");
-    /** Visually-hidden container for the screen-reader data-table fallback. */
-    __publicField(this, "a11y");
-    __publicField(this, "width", 0);
-    __publicField(this, "height", 0);
-    __publicField(this, "dpr", 1);
-    /**
-     * When true, overlay text (axis labels, titles, legends, annotation labels) is
-     * painted onto the `marks` canvas instead of the HTML overlay. Set by headless
-     * renderers (`@graphein/node`) where there is no DOM to host crisp text.
-     * Defaults to false (browser).
-     */
-    __publicField(this, "headless", false);
-    this.container = container;
-    this.root = createDiv("graphein-root", {
-      position: "relative",
-      width: "100%",
-      height: "100%",
-      overflow: "hidden"
-    });
-    const marksCanvas = document.createElement("canvas");
-    marksCanvas.className = "graphein-layer-marks";
-    setStyle(marksCanvas, { ...fillParentStyle });
-    const interactionCanvas = document.createElement("canvas");
-    interactionCanvas.className = "graphein-layer-interaction";
-    setStyle(interactionCanvas, { ...fillParentStyle, pointerEvents: "none" });
-    this.overlay = createDiv("graphein-layer-overlay", {
-      ...fillParentStyle,
-      width: "100%",
-      height: "100%",
-      pointerEvents: "none"
-    });
-    this.a11y = createDiv("graphein-a11y", {
-      position: "absolute",
-      width: "1px",
-      height: "1px",
-      overflow: "hidden",
-      clip: "rect(0 0 0 0)",
-      clipPath: "inset(50%)",
-      whiteSpace: "nowrap",
-      border: "0",
-      margin: "-1px",
-      padding: "0"
-    });
-    this.root.appendChild(marksCanvas);
-    this.root.appendChild(interactionCanvas);
-    this.root.appendChild(this.overlay);
-    this.root.appendChild(this.a11y);
-    container.appendChild(this.root);
-    this.marks = new CanvasLayer(marksCanvas);
-    this.interaction = new CanvasLayer(interactionCanvas);
-  }
-  resize(width, height, dpr = getDevicePixelRatio()) {
-    this.width = width;
-    this.height = height;
-    this.dpr = dpr;
-    this.marks.resize(width, height, dpr);
-    this.interaction.resize(width, height, dpr);
-    setStyle(this.overlay, { width: `${width}px`, height: `${height}px` });
+// src/render/text.ts
+var measureCtx;
+var injectedCtx = null;
+function setMeasureContext(ctx) {
+  injectedCtx = ctx;
+}
+function getMeasureCtx() {
+  if (injectedCtx) return injectedCtx;
+  if (measureCtx !== void 0) return measureCtx;
+  try {
+    measureCtx = document.createElement("canvas").getContext("2d");
+  } catch {
+    measureCtx = null;
   }
-  /** Clear both canvas layers and empty the HTML overlay. */
-  clear() {
-    this.marks.clear();
-    this.interaction.clear();
-    this.overlay.replaceChildren();
+  return measureCtx;
+}
+function fallbackCharWidth(code) {
+  const wide = code >= 4352 && code <= 4447 || code >= 11904 && code <= 42191 || code >= 44032 && code <= 55203 || code >= 63744 && code <= 64255 || code >= 65072 && code <= 65135 || code >= 65280 && code <= 65376 || code >= 65504 && code <= 65510 || code > 65535;
+  return wide ? 1 : 0.55;
+}
+function measureText(text2, font) {
+  const ctx = getMeasureCtx();
+  if (!ctx) {
+    const sizeMatch = /(\d+(?:\.\d+)?)px/.exec(font);
+    const size = sizeMatch ? parseFloat(sizeMatch[1]) : 12;
+    let ems = 0;
+    for (const ch of text2) ems += fallbackCharWidth(ch.codePointAt(0) ?? 0);
+    return { width: ems * size };
   }
-  /** Remove all DOM created by this Surface. */
-  destroy() {
-    this.clear();
-    this.root.remove();
+  ctx.font = font;
+  return { width: ctx.measureText(text2).width };
+}
+function fontString(size, family, weight = 400, style = "normal") {
+  return `${style} ${weight} ${size}px ${family}`;
+}
+function ellipsize(text2, maxWidth, font) {
+  if (maxWidth <= 0 || text2.length === 0) return "";
+  if (measureText(text2, font).width <= maxWidth) return text2;
+  const ellipsis = "\u2026";
+  const ellipsisW = measureText(ellipsis, font).width;
+  if (ellipsisW > maxWidth) return "";
+  let lo = 0;
+  let hi = text2.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (measureText(text2.slice(0, mid) + ellipsis, font).width <= maxWidth) lo = mid;
+    else hi = mid - 1;
   }
-};
+  return text2.slice(0, lo) + ellipsis;
+}
 
 // src/render/overlayText.ts
 function paintCanvasText(ctx, c) {
@@ -5860,53 +6199,155 @@ function paintLegendSwatch(ctx, x, midY, symbol, color, swatch = 11) {
   ctx.restore();
 }
 
-// src/render/text.ts
-var measureCtx;
-var injectedCtx = null;
-function setMeasureContext(ctx) {
-  injectedCtx = ctx;
-}
-function getMeasureCtx() {
-  if (injectedCtx) return injectedCtx;
-  if (measureCtx !== void 0) return measureCtx;
-  try {
-    measureCtx = document.createElement("canvas").getContext("2d");
-  } catch {
-    measureCtx = null;
+// src/render/labelLedger.ts
+var LINE_HEIGHT = 1.2;
+var LabelLedger = class {
+  constructor() {
+    __publicField(this, "records", []);
   }
-  return measureCtx;
-}
-function measureText(text, font) {
-  const ctx = getMeasureCtx();
-  if (!ctx) {
-    const sizeMatch = /(\d+(?:\.\d+)?)px/.exec(font);
-    const size = sizeMatch ? parseFloat(sizeMatch[1]) : 12;
-    return { width: text.length * size * 0.55 };
+  add(record) {
+    this.records.push(record);
   }
-  ctx.font = font;
-  return { width: ctx.measureText(text).width };
+  clear() {
+    this.records.length = 0;
+  }
+  /** Records matching any of `roles`. */
+  byRole(...roles) {
+    return this.records.filter((r) => roles.includes(r.role));
+  }
+};
+function recordLabel(ledger, record) {
+  ledger?.add(record);
+}
+function fitLabel(text2, budget, font) {
+  if (budget == null || budget <= 0) return { text: text2, truncated: false };
+  if (measureText(text2, font).width <= budget) return { text: text2, truncated: false };
+  return { text: ellipsize(text2, budget, font), truncated: true };
+}
+function labelBox(o, font) {
+  const cmd = overlayTextToCanvasCmd(o, font);
+  const width = measureText(o.text, font).width;
+  const height = o.size * LINE_HEIGHT;
+  const x = cmd.align === "right" ? cmd.x - width : cmd.align === "center" ? cmd.x - width / 2 : cmd.x;
+  const y = cmd.baseline === "middle" ? cmd.y - height / 2 : cmd.baseline === "alphabetic" ? cmd.y - height : cmd.y;
+  const radians = cmd.rotate ?? 0;
+  if (!radians) return { box: { x, y, width, height }, angle: 0 };
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+  const xs = [];
+  const ys = [];
+  for (const [px, py] of [
+    [x, y],
+    [x + width, y],
+    [x, y + height],
+    [x + width, y + height]
+  ]) {
+    const dx = px - cmd.x;
+    const dy = py - cmd.y;
+    xs.push(cmd.x + dx * cos - dy * sin);
+    ys.push(cmd.y + dx * sin + dy * cos);
+  }
+  const minX = Math.min(...xs);
+  const minY = Math.min(...ys);
+  return {
+    box: { x: minX, y: minY, width: Math.max(...xs) - minX, height: Math.max(...ys) - minY },
+    angle: radians * 180 / Math.PI
+  };
 }
-function fontString(size, family, weight = 400, style = "normal") {
-  return `${style} ${weight} ${size}px ${family}`;
+function boxesOverlap(a, b, tolerance2 = 0) {
+  return a.x + a.width - tolerance2 > b.x && b.x + b.width - tolerance2 > a.x && a.y + a.height - tolerance2 > b.y && b.y + b.height - tolerance2 > a.y;
 }
-function ellipsize(text, maxWidth, font) {
-  if (maxWidth <= 0 || text.length === 0) return "";
-  if (measureText(text, font).width <= maxWidth) return text;
-  const ellipsis = "\u2026";
-  const ellipsisW = measureText(ellipsis, font).width;
-  if (ellipsisW > maxWidth) return "";
-  let lo = 0;
-  let hi = text.length;
-  while (lo < hi) {
-    const mid = Math.ceil((lo + hi) / 2);
-    if (measureText(text.slice(0, mid) + ellipsis, font).width <= maxWidth) lo = mid;
-    else hi = mid - 1;
+
+// src/render/surface.ts
+var Surface = class {
+  constructor(container) {
+    __publicField(this, "container");
+    __publicField(this, "root");
+    __publicField(this, "marks");
+    __publicField(this, "interaction");
+    __publicField(this, "overlay");
+    /** Visually-hidden container for the screen-reader data-table fallback. */
+    __publicField(this, "a11y");
+    __publicField(this, "width", 0);
+    __publicField(this, "height", 0);
+    __publicField(this, "dpr", 1);
+    /**
+     * When true, overlay text (axis labels, titles, legends, annotation labels) is
+     * painted onto the `marks` canvas instead of the HTML overlay. Set by headless
+     * renderers (`@graphein/node`) where there is no DOM to host crisp text.
+     * Defaults to false (browser).
+     */
+    __publicField(this, "headless", false);
+    /**
+     * Every overlay label drawn during the current pass, recorded by the text
+     * helpers in `axes/draw.ts` and `charts/chrome.ts`. The render report reads it
+     * to detect clipped and colliding text for any chart type, cartesian or not.
+     */
+    __publicField(this, "labels", new LabelLedger());
+    this.container = container;
+    this.root = createDiv("graphein-root", {
+      position: "relative",
+      width: "100%",
+      height: "100%",
+      overflow: "hidden"
+    });
+    const marksCanvas = document.createElement("canvas");
+    marksCanvas.className = "graphein-layer-marks";
+    setStyle(marksCanvas, { ...fillParentStyle });
+    const interactionCanvas = document.createElement("canvas");
+    interactionCanvas.className = "graphein-layer-interaction";
+    setStyle(interactionCanvas, { ...fillParentStyle, pointerEvents: "none" });
+    this.overlay = createDiv("graphein-layer-overlay", {
+      ...fillParentStyle,
+      width: "100%",
+      height: "100%",
+      pointerEvents: "none"
+    });
+    this.a11y = createDiv("graphein-a11y", {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      overflow: "hidden",
+      clip: "rect(0 0 0 0)",
+      clipPath: "inset(50%)",
+      whiteSpace: "nowrap",
+      border: "0",
+      margin: "-1px",
+      padding: "0"
+    });
+    this.root.appendChild(marksCanvas);
+    this.root.appendChild(interactionCanvas);
+    this.root.appendChild(this.overlay);
+    this.root.appendChild(this.a11y);
+    container.appendChild(this.root);
+    this.marks = new CanvasLayer(marksCanvas);
+    this.interaction = new CanvasLayer(interactionCanvas);
   }
-  return text.slice(0, lo) + ellipsis;
-}
+  resize(width, height, dpr = getDevicePixelRatio()) {
+    this.width = width;
+    this.height = height;
+    this.dpr = dpr;
+    this.marks.resize(width, height, dpr);
+    this.interaction.resize(width, height, dpr);
+    setStyle(this.overlay, { width: `${width}px`, height: `${height}px` });
+  }
+  /** Clear both canvas layers, empty the HTML overlay, and reset the ledger. */
+  clear() {
+    this.marks.clear();
+    this.interaction.clear();
+    this.overlay.replaceChildren();
+    this.labels.clear();
+  }
+  /** Remove all DOM created by this Surface. */
+  destroy() {
+    this.clear();
+    this.root.remove();
+  }
+};
 
 // src/theme/tokens.ts
-var PALETTE = categorical("graphein");
+var LIGHT_PALETTE = categorical("graphein");
+var DARK_PALETTE = adaptPaletteForDarkBackground(LIGHT_PALETTE, "#0b1220");
 var FONT_FAMILY = 'Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif';
 var SHARED = {
   font: {
@@ -5930,7 +6371,7 @@ var lightTheme = {
     grid: "#eef2f6",
     border: "#e2e8f0",
     accent: "#0d9488",
-    palette: PALETTE,
+    palette: LIGHT_PALETTE,
     positive: "#16a34a",
     negative: "#dc2626"
   },
@@ -5948,7 +6389,7 @@ var darkTheme = {
     grid: "#1c2740",
     border: "#1e293b",
     accent: "#2dd4bf",
-    palette: PALETTE,
+    palette: DARK_PALETTE,
     positive: "#22c55e",
     negative: "#f87171"
   },
@@ -5961,6 +6402,18 @@ var themes = {
 function isPlainObject(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
+var COLOR_FIELDS = [
+  "background",
+  "surface",
+  "text",
+  "textMuted",
+  "axis",
+  "grid",
+  "border",
+  "accent",
+  "positive",
+  "negative"
+];
 function deepMerge(base, override) {
   if (!isPlainObject(override)) return base;
   if (!isPlainObject(base)) return override;
@@ -5975,13 +6428,57 @@ function deepMerge(base, override) {
   }
   return out;
 }
+function addInvalidColorWarning(warnings, path) {
+  warnings.push({ path, message: `Invalid color token at ${path}; using the base theme value.` });
+}
+function fallbackPaletteColor(base, index) {
+  return base.color.palette[index] ?? base.color.palette[index % base.color.palette.length] ?? "#000000";
+}
+function sanitizeThemeOverride(base, override, warnings) {
+  const sanitized = { ...override };
+  if (!("color" in override)) return sanitized;
+  const color = override.color;
+  if (!isPlainObject(color)) {
+    addInvalidColorWarning(warnings, "color");
+    sanitized.color = base.color;
+    return sanitized;
+  }
+  const colorOut = { ...color };
+  for (const key of COLOR_FIELDS) {
+    if (!(key in color)) continue;
+    const value = color[key];
+    if (typeof value === "string" && parseColor(value)) continue;
+    addInvalidColorWarning(warnings, `color.${key}`);
+    colorOut[key] = base.color[key];
+  }
+  if ("palette" in color) {
+    const palette = color.palette;
+    if (Array.isArray(palette)) {
+      colorOut.palette = palette.map((value, index) => {
+        if (typeof value === "string" && parseColor(value)) return value;
+        addInvalidColorWarning(warnings, `color.palette.${index}`);
+        return fallbackPaletteColor(base, index);
+      });
+    } else {
+      addInvalidColorWarning(warnings, "color.palette");
+      colorOut.palette = base.color.palette;
+    }
+  }
+  sanitized.color = colorOut;
+  return sanitized;
+}
 function resolveTheme(theme) {
-  if (theme == null) return lightTheme;
-  if (typeof theme === "string") return themes[theme] ?? lightTheme;
+  return resolveThemeChecked(theme).tokens;
+}
+function resolveThemeChecked(theme) {
+  if (theme == null) return { tokens: lightTheme, warnings: [] };
+  if (typeof theme === "string") return { tokens: themes[theme] ?? lightTheme, warnings: [] };
   const baseName = theme.base ?? (theme.dark ? "dark" : "light");
   const base = themes[baseName] ?? lightTheme;
   const { base: _ignored, ...override } = theme;
-  return deepMerge(base, override);
+  const warnings = [];
+  const sanitized = sanitizeThemeOverride(base, override, warnings);
+  return { tokens: deepMerge(base, sanitized), warnings };
 }
 
 // src/theme/sketch.ts
@@ -6082,24 +6579,131 @@ function inferFieldTypes(data) {
 
 // src/spec/repair.ts
 var MAX_PASSES = 8;
-function repairSpec(spec) {
+function isObject4(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function pathValue(doc, path) {
+  if (path === "") return doc;
+  let current = doc;
+  for (const part of path.replace(/\[(\d+)\]/g, ".$1").split(".")) {
+    if (part === "") continue;
+    if (Array.isArray(current)) {
+      current = current[Number(part)];
+    } else if (isObject4(current)) {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function dataRows(spec) {
+  if (!isObject4(spec) || !Array.isArray(spec.data) || spec.data.length === 0) return void 0;
+  return spec.data.filter(isObject4);
+}
+function dataColumns(spec) {
+  const rows = dataRows(spec);
+  if (!rows || rows.length === 0) return [];
+  return [...new Set(rows.flatMap((row) => Object.keys(row)))];
+}
+function rationaleForValidationFix(op) {
+  return `validator-provided safe fix at "${op.path}"`;
+}
+function uniqueRecommendedSpec(spec) {
+  const rows = dataRows(spec);
+  if (!rows) return void 0;
+  const recommendations = recommendChart(rows, { maxResults: 20 });
+  if (recommendations.length === 0) return void 0;
+  const [top, runnerUp] = recommendations;
+  if (runnerUp && runnerUp.score === top.score) return void 0;
+  return top.spec;
+}
+function uniqueRecommendationForType(spec, type) {
+  const rows = dataRows(spec);
+  if (!rows) return void 0;
+  const matches = recommendChart(rows, { maxResults: 20 }).filter((rec) => {
+    return isObject4(rec.spec) && rec.spec.type === type;
+  });
+  return matches.length === 1 ? matches[0].spec : void 0;
+}
+function collectDataFixes(spec, findings) {
+  if (!isObject4(spec)) return [];
+  const repairs = [];
+  const columns = dataColumns(spec);
+  for (const finding of findings) {
+    if (finding.suggestion?.kind !== "field") continue;
+    const value = pathValue(spec, finding.path);
+    if (typeof value !== "string") continue;
+    const best = closest(value, columns);
+    if (!best || best === value) continue;
+    repairs.push({
+      op: { op: "replace", path: toPointer(finding.path), value: best },
+      rationale: `field "${value}" \u2192 "${best}" (nearest column)`
+    });
+  }
+  if (pathValue(spec, "type") === void 0) {
+    const recommended = uniqueRecommendedSpec(spec);
+    if (isObject4(recommended) && typeof recommended.type === "string") {
+      repairs.push({
+        op: { op: "add", path: "/type", value: recommended.type },
+        rationale: `type "${recommended.type}" inferred from data shape`
+      });
+    }
+  }
+  const type = pathValue(spec, "type");
+  const encoding = pathValue(spec, "encoding");
+  if (typeof type === "string") {
+    const recommended = uniqueRecommendationForType(spec, type);
+    const recommendedEncoding = isObject4(recommended) ? recommended.encoding : void 0;
+    if (isObject4(recommendedEncoding)) {
+      if (!isObject4(encoding) && findings.some((finding) => finding.path === "encoding")) {
+        repairs.push({
+          op: { op: "add", path: "/encoding", value: recommendedEncoding },
+          rationale: `encoding inferred from data shape for "${type}"`
+        });
+      } else if (isObject4(encoding)) {
+        for (const finding of findings) {
+          const match = /^encoding\.([^.]+)$/.exec(finding.path);
+          if (!match) continue;
+          const channel = match[1];
+          if (encoding[channel] !== void 0 || recommendedEncoding[channel] === void 0) continue;
+          repairs.push({
+            op: { op: "add", path: toPointer(finding.path), value: recommendedEncoding[channel] },
+            rationale: `channel "${channel}" inferred from data shape for "${type}"`
+          });
+        }
+      }
+    }
+  }
+  return repairs;
+}
+function repairSpec(spec, options = {}) {
   let current = spec;
   const applied = [];
+  const appliedDetails = [];
   let prevSignature = "";
+  const level = options.level ?? "safe";
   for (let pass = 0; pass < MAX_PASSES; pass++) {
     const { errors, warnings } = validateSpec(current);
     const fixes = [];
     for (const finding of [...errors, ...warnings]) {
-      if (finding.fix && finding.fix.length > 0) fixes.push(...finding.fix);
+      if (finding.fix && finding.fix.length > 0) {
+        fixes.push(...finding.fix.map((op) => ({ op, rationale: rationaleForValidationFix(op) })));
+      }
+    }
+    if (level === "data" && fixes.length === 0) {
+      fixes.push(...collectDataFixes(current, [...errors, ...warnings]));
     }
     if (fixes.length === 0) break;
-    const signature = JSON.stringify(fixes);
+    const ops = fixes.map((fix) => fix.op);
+    const signature = JSON.stringify(ops);
     if (signature === prevSignature) break;
     prevSignature = signature;
-    current = applyPatch(current, fixes);
-    applied.push(...fixes);
+    current = applyPatch(current, ops);
+    applied.push(...ops);
+    appliedDetails.push(...fixes);
   }
-  return { spec: current, applied, remaining: validateSpec(current).errors };
+  return { spec: current, applied, appliedDetails, remaining: validateSpec(current).errors };
 }
 
 // src/spec/sketch.ts
@@ -6125,75 +6729,534 @@ function resolveSketch(spec) {
   };
 }
 
+// src/spec/templates.ts
+var STARTER_SPECS = {
+  line: {
+    type: "line",
+    title: "Monthly users",
+    data: [
+      { month: "2024-01", users: 42 },
+      { month: "2024-02", users: 58 },
+      { month: "2024-03", users: 64 }
+    ],
+    encoding: {
+      x: { field: "month", type: "temporal" },
+      y: { field: "users" }
+    }
+  },
+  area: {
+    type: "area",
+    title: "Monthly revenue",
+    data: [
+      { month: "2024-01", revenue: 120 },
+      { month: "2024-02", revenue: 150 },
+      { month: "2024-03", revenue: 180 }
+    ],
+    encoding: {
+      x: { field: "month", type: "temporal" },
+      y: { field: "revenue" }
+    }
+  },
+  bar: {
+    type: "bar",
+    title: "Sales by region",
+    data: [
+      { region: "North", sales: 120 },
+      { region: "South", sales: 95 },
+      { region: "West", sales: 140 }
+    ],
+    encoding: {
+      x: { field: "region" },
+      y: { field: "sales" }
+    }
+  },
+  scatter: {
+    type: "scatter",
+    title: "Price vs. demand",
+    data: [
+      { price: 10, demand: 80 },
+      { price: 15, demand: 65 },
+      { price: 20, demand: 48 }
+    ],
+    encoding: {
+      x: { field: "price" },
+      y: { field: "demand" }
+    }
+  },
+  combo: {
+    type: "combo",
+    title: "Revenue and margin",
+    data: [
+      { month: "Jan", revenue: 120, margin: 0.31 },
+      { month: "Feb", revenue: 150, margin: 0.35 },
+      { month: "Mar", revenue: 135, margin: 0.33 }
+    ],
+    encoding: {
+      x: { field: "month" }
+    },
+    layers: [
+      { mark: "bar", encoding: { y: { field: "revenue" } } },
+      { mark: "line", axis: "right", encoding: { y: { field: "margin", format: ".0%" } } }
+    ]
+  },
+  histogram: {
+    type: "histogram",
+    title: "Order value distribution",
+    data: [
+      { value: 12 },
+      { value: 18 },
+      { value: 25 },
+      { value: 32 }
+    ],
+    encoding: {
+      x: { field: "value" }
+    }
+  },
+  pie: {
+    type: "pie",
+    title: "Share by channel",
+    data: [
+      { channel: "Direct", share: 45 },
+      { channel: "Partner", share: 30 },
+      { channel: "Search", share: 25 }
+    ],
+    encoding: {
+      theta: { field: "share" },
+      color: { field: "channel" }
+    }
+  },
+  heatmap: {
+    type: "heatmap",
+    title: "Activity by day and hour",
+    data: [
+      { day: "Mon", hour: "Morning", activity: 12 },
+      { day: "Mon", hour: "Evening", activity: 18 },
+      { day: "Tue", hour: "Morning", activity: 9 },
+      { day: "Tue", hour: "Evening", activity: 21 }
+    ],
+    encoding: {
+      x: { field: "day" },
+      y: { field: "hour" },
+      color: { field: "activity" }
+    }
+  },
+  funnel: {
+    type: "funnel",
+    title: "Signup conversion",
+    data: [
+      { stage: "Visitors", users: 1e3 },
+      { stage: "Trials", users: 420 },
+      { stage: "Customers", users: 180 }
+    ],
+    encoding: {
+      stage: { field: "stage" },
+      value: { field: "users" }
+    }
+  },
+  kpi: {
+    type: "kpi",
+    title: "Total revenue",
+    data: [
+      { revenue: 120 },
+      { revenue: 150 }
+    ],
+    value: { field: "revenue", aggregate: "sum" },
+    label: "Revenue"
+  },
+  treemap: {
+    type: "treemap",
+    title: "Portfolio value",
+    data: [
+      { category: "Product A", value: 60 },
+      { category: "Product B", value: 40 },
+      { category: "Product C", value: 25 }
+    ],
+    encoding: {
+      category: { field: "category" },
+      value: { field: "value" }
+    }
+  },
+  gauge: {
+    type: "gauge",
+    title: "Quota attainment",
+    data: [
+      { attainment: 72 },
+      { attainment: 81 }
+    ],
+    value: { field: "attainment", aggregate: "mean" },
+    max: 100,
+    label: "Attainment"
+  },
+  bullet: {
+    type: "bullet",
+    title: "Revenue vs. target",
+    data: [
+      { revenue: 72 },
+      { revenue: 81 }
+    ],
+    value: { field: "revenue", aggregate: "mean" },
+    target: 90,
+    max: 100,
+    label: "Revenue"
+  },
+  calendarHeatmap: {
+    type: "calendarHeatmap",
+    title: "Daily activity",
+    data: [
+      { date: "2024-01-01", value: 3 },
+      { date: "2024-01-02", value: 7 },
+      { date: "2024-01-03", value: 4 }
+    ],
+    encoding: {
+      date: { field: "date", type: "temporal" },
+      color: { field: "value" }
+    }
+  },
+  waterfall: {
+    type: "waterfall",
+    title: "Profit bridge",
+    data: [
+      { stage: "Start", change: 100 },
+      { stage: "Growth", change: 35 },
+      { stage: "Costs", change: -20 }
+    ],
+    encoding: {
+      stage: { field: "stage" },
+      value: { field: "change" }
+    }
+  },
+  slope: {
+    type: "slope",
+    title: "Before and after",
+    data: [
+      { period: "Before", score: 42, segment: "A" },
+      { period: "After", score: 58, segment: "A" },
+      { period: "Before", score: 35, segment: "B" },
+      { period: "After", score: 46, segment: "B" }
+    ],
+    encoding: {
+      x: { field: "period" },
+      y: { field: "score" },
+      series: { field: "segment" }
+    }
+  },
+  dumbbell: {
+    type: "dumbbell",
+    title: "Before and after by category",
+    data: [
+      { category: "A", value: 42, group: "Before" },
+      { category: "A", value: 58, group: "After" },
+      { category: "B", value: 35, group: "Before" },
+      { category: "B", value: 46, group: "After" }
+    ],
+    encoding: {
+      category: { field: "category" },
+      value: { field: "value" },
+      group: { field: "group" }
+    }
+  },
+  table: {
+    type: "table",
+    title: "Regional sales",
+    data: [
+      { region: "North", sales: 120 },
+      { region: "South", sales: 95 }
+    ]
+  },
+  matrix: {
+    type: "matrix",
+    title: "Sales matrix",
+    data: [
+      { region: "North", segment: "Consumer", sales: 120 },
+      { region: "South", segment: "Business", sales: 95 }
+    ],
+    rows: ["region"],
+    columns: ["segment"],
+    values: [{ field: "sales", op: "sum" }]
+  },
+  box: {
+    type: "box",
+    title: "Latency by tier",
+    data: [
+      { tier: "Free", latency: 120 },
+      { tier: "Free", latency: 180 },
+      { tier: "Pro", latency: 90 },
+      { tier: "Pro", latency: 110 }
+    ],
+    encoding: {
+      x: { field: "tier" },
+      y: { field: "latency" }
+    }
+  },
+  sankey: {
+    type: "sankey",
+    title: "Traffic flow",
+    data: [
+      { source: "Visits", target: "Signup", value: 100 },
+      { source: "Signup", target: "Trial", value: 60 },
+      { source: "Trial", target: "Paid", value: 25 }
+    ],
+    encoding: {
+      source: { field: "source" },
+      target: { field: "target" },
+      value: { field: "value" }
+    }
+  },
+  choropleth: {
+    type: "choropleth",
+    title: "Regional index",
+    geo: {
+      type: "FeatureCollection",
+      features: [
+        {
+          type: "Feature",
+          properties: { id: "A" },
+          geometry: { type: "Polygon", coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]] }
+        },
+        {
+          type: "Feature",
+          properties: { id: "B" },
+          geometry: { type: "Polygon", coordinates: [[[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]]] }
+        }
+      ]
+    },
+    data: [
+      { region: "A", value: 42 },
+      { region: "B", value: 88 }
+    ],
+    encoding: {
+      key: { field: "region" },
+      color: { field: "value" }
+    },
+    featureId: "id",
+    projection: "identity"
+  },
+  dropdown: {
+    type: "dropdown",
+    title: "Region filter",
+    data: [
+      { region: "North" },
+      { region: "South" }
+    ],
+    field: "region"
+  },
+  search: {
+    type: "search",
+    title: "Customer search",
+    data: [
+      { customer: "Acme" },
+      { customer: "Globex" }
+    ],
+    field: "customer"
+  },
+  list: {
+    type: "list",
+    title: "Category filter",
+    data: [
+      { category: "Hardware" },
+      { category: "Software" }
+    ],
+    field: "category"
+  },
+  range: {
+    type: "range",
+    title: "Price range",
+    data: [
+      { price: 10 },
+      { price: 25 }
+    ],
+    field: "price"
+  },
+  dateRange: {
+    type: "dateRange",
+    title: "Date range",
+    data: [
+      { date: "2024-01-01" },
+      { date: "2024-01-31" }
+    ],
+    field: "date"
+  }
+};
+var CHART_TYPE_PURPOSES = {
+  line: "Trend over time",
+  area: "Part-to-whole or filled trend over time",
+  bar: "Compare categories",
+  scatter: "Correlation or distribution across two measures",
+  combo: "Two measures or mark types on a shared axis",
+  histogram: "Distribution of one quantitative measure",
+  pie: "Composition of a total",
+  heatmap: "Density across two categories",
+  funnel: "Conversion through stages",
+  kpi: "Single headline value or compact scorecard",
+  treemap: "Hierarchical or categorical part-to-whole",
+  gauge: "Single value against a scale",
+  bullet: "Compact KPI versus a target",
+  calendarHeatmap: "Daily values over a year",
+  waterfall: "Running total or bridge of signed deltas",
+  slope: "Before/after change across series",
+  dumbbell: "Gap between two groups by category",
+  table: "Tabular detail",
+  matrix: "Pivot or cross-tab summary",
+  box: "Spread and distribution by group",
+  sankey: "Flows between nodes",
+  choropleth: "Values over map regions",
+  dropdown: "Single- or multi-select field filter",
+  search: "Text search filter for a field",
+  list: "Checkbox list filter for a field",
+  range: "Numeric range filter for a field",
+  dateRange: "Temporal range filter for a field"
+};
+var REQUIRED_TEMPLATE_CHANNELS = {
+  line: ["x", "y"],
+  area: ["x", "y"],
+  bar: ["x", "y"],
+  scatter: ["x", "y"],
+  combo: ["x", "layers[].mark", "layers[].encoding.y"],
+  histogram: ["x"],
+  pie: ["theta", "color"],
+  heatmap: ["x", "y", "color"],
+  funnel: ["stage", "value"],
+  kpi: ["value"],
+  treemap: ["category", "value"],
+  gauge: ["value", "max"],
+  bullet: ["value"],
+  calendarHeatmap: ["date", "color"],
+  waterfall: ["stage", "value"],
+  slope: ["x", "y", "series"],
+  dumbbell: ["category", "value", "group"],
+  table: [],
+  matrix: ["rows", "values"],
+  box: ["x", "y"],
+  sankey: ["source", "target", "value"],
+  choropleth: ["geo", "key", "color", "featureId"],
+  dropdown: ["field"],
+  search: ["field"],
+  list: ["field"],
+  range: ["field"],
+  dateRange: ["field"]
+};
+function cloneSpec(spec) {
+  return JSON.parse(JSON.stringify(spec));
+}
+function starterSpec(type) {
+  return cloneSpec(STARTER_SPECS[type]);
+}
+function listChartTypes() {
+  return CHART_TYPES.map((type) => ({
+    type,
+    purpose: CHART_TYPE_PURPOSES[type],
+    requiredChannels: [...REQUIRED_TEMPLATE_CHANNELS[type]],
+    example: starterSpec(type)
+  }));
+}
+
 // src/layout/frame.ts
 var TICK_SIZE = 6;
 var NO_PADDING = { top: 0, right: 0, bottom: 0, left: 0 };
 var AXIS_LABEL_GAP = 6;
 var AXIS_TITLE_GAP = 4;
+var MAX_Y_GUTTER_FRACTION = 0.35;
+var MAX_X_BAND_FRACTION = 0.4;
+var MAX_LEGEND_WIDTH_FRACTION = 0.3;
 var LEGEND_SWATCH = 11;
 var LEGEND_SWATCH_GAP = 6;
 var LEGEND_ITEM_GAP = 16;
 var LEGEND_ROW_GAP = 6;
 var LEGEND_PAD = 4;
+var MIN_VIABLE_PLOT_SIZE = 24;
+var COMPACT_PLOT_WIDTH = 300;
+var COMPACT_PLOT_HEIGHT = 180;
 var lineHeight = (size) => Math.round(size * 1.35);
+function metricsForDensity(density, font) {
+  return {
+    axisLabelGap: AXIS_LABEL_GAP,
+    axisTitleGap: AXIS_TITLE_GAP,
+    tickSize: TICK_SIZE,
+    legendSwatch: LEGEND_SWATCH,
+    legendSwatchGap: LEGEND_SWATCH_GAP,
+    legendItemGap: LEGEND_ITEM_GAP,
+    legendRowGap: LEGEND_ROW_GAP,
+    legendPad: LEGEND_PAD,
+    titleGap: font.size.base
+  };
+}
+function fontForDensity(font, density) {
+  return font;
+}
 function resolveXLabelAngle(axis, available, font) {
   if (axis.labelAngle != null) return Math.max(0, Math.min(90, axis.labelAngle));
   const labels = axis.labels;
   if (axis.edgeAnchored || labels.length < 2 || available <= 0) return 0;
   const wfont = fontString(font.size.small, font.family, font.weight.normal);
   const widest = Math.max(...labels.map((l) => measureText(l, wfont).width));
-  const needed = widest + 10;
-  return available / labels.length >= needed ? 0 : 45;
+  const slot = available / labels.length;
+  if (slot >= widest + 10) return 0;
+  return slot * Math.SQRT1_2 >= font.size.small ? 45 : 90;
 }
-function legendItemWidth(label, font) {
+function legendItemWidth(label, font, m) {
   const w = measureText(label, fontString(font.size.small, font.family, font.weight.normal)).width;
-  return LEGEND_SWATCH + LEGEND_SWATCH_GAP + Math.ceil(w);
+  return m.legendSwatch + m.legendSwatchGap + Math.ceil(w);
 }
-function layoutLegend(items, position, font, maxWidth, maxHeight) {
-  const rowH = Math.max(LEGEND_SWATCH, lineHeight(font.size.small));
+function layoutLegend(items, position, font, m, maxWidth, maxHeight) {
+  const rowH = Math.max(m.legendSwatch, lineHeight(font.size.small));
   const horizontal = position === "top" || position === "bottom";
   if (horizontal) {
-    const rows = [[]];
+    const rows2 = [[]];
     let x = 0;
     let row = 0;
     for (const item of items) {
-      const w = legendItemWidth(item.label, font);
+      const w = legendItemWidth(item.label, font, m);
       if (x > 0 && x + w > maxWidth) {
         row++;
-        rows[row] = [];
+        rows2[row] = [];
         x = 0;
       }
-      rows[row].push({ ...item, x, y: row * (rowH + LEGEND_ROW_GAP), width: w });
-      x += w + LEGEND_ITEM_GAP;
+      rows2[row].push({ ...item, x, y: row * (rowH + m.legendRowGap), width: w });
+      x += w + m.legendItemGap;
     }
     const widest = Math.max(
       0,
-      ...rows.map((r) => r.reduce((acc, it) => acc + it.width + LEGEND_ITEM_GAP, -LEGEND_ITEM_GAP))
+      ...rows2.map((r) => r.reduce((acc, it) => acc + it.width + m.legendItemGap, -16))
     );
-    const height2 = rows.length * rowH + (rows.length - 1) * LEGEND_ROW_GAP;
+    const height2 = rows2.length * rowH + (rows2.length - 1) * m.legendRowGap;
     const blockWidth = Math.min(maxWidth, widest);
     const positioned2 = [];
-    for (const r of rows) {
-      const rowWidth = r.reduce((acc, it) => acc + it.width + LEGEND_ITEM_GAP, -LEGEND_ITEM_GAP);
+    for (const r of rows2) {
+      const rowWidth = r.reduce((acc, it) => acc + it.width + m.legendItemGap, -16);
       const offset = Math.max(0, (blockWidth - rowWidth) / 2);
       for (const it of r) positioned2.push({ ...it, x: it.x + offset });
     }
-    return { width: blockWidth, height: height2 + LEGEND_PAD * 2, items: positioned2 };
+    return { width: blockWidth, height: height2 + m.legendPad * 2, items: positioned2, overflow: 0 };
   }
-  const maxRows = Math.max(1, Math.floor((maxHeight + LEGEND_ROW_GAP) / (rowH + LEGEND_ROW_GAP)));
-  const shown = items.slice(0, maxRows);
-  const width = Math.max(0, ...shown.map((it) => legendItemWidth(it.label, font)));
+  const maxRows = Math.max(1, Math.floor((maxHeight + m.legendRowGap) / (rowH + m.legendRowGap)));
+  const overflowing = items.length > maxRows;
+  const shown = overflowing ? items.slice(0, Math.max(0, maxRows - 1)) : items;
+  const overflow = items.length - shown.length;
+  const cap2 = Math.max(0, maxWidth * MAX_LEGEND_WIDTH_FRACTION);
+  const natural = Math.max(0, ...shown.map((it) => legendItemWidth(it.label, font, m)));
+  const width = Math.min(natural, cap2);
   const positioned = shown.map((it, i) => ({
     ...it,
     x: 0,
-    y: i * (rowH + LEGEND_ROW_GAP),
-    width: legendItemWidth(it.label, font)
+    y: i * (rowH + m.legendRowGap),
+    width: Math.min(legendItemWidth(it.label, font, m), width)
   }));
-  const height = shown.length * rowH + (shown.length - 1) * LEGEND_ROW_GAP;
-  return { width: width + LEGEND_PAD * 2, height, items: positioned };
+  const rows = shown.length + (overflow > 0 ? 1 : 0);
+  const height = Math.max(0, rows * rowH + (rows - 1) * m.legendRowGap);
+  const overflowRow = overflow > 0 ? { x: 0, y: shown.length * (rowH + m.legendRowGap), width, height: rowH } : void 0;
+  return { width: width + m.legendPad * 2, height, items: positioned, overflow, overflowRow };
 }
-function computeFrame(input) {
+function viable(plot) {
+  return plot.width >= MIN_VIABLE_PLOT_SIZE && plot.height >= MIN_VIABLE_PLOT_SIZE;
+}
+function resolveDensity(frame) {
+  return frame.plot.width < COMPACT_PLOT_WIDTH || frame.plot.height < COMPACT_PLOT_HEIGHT ? "compact" : "comfortable";
+}
+function computeFramePass(input, density, dropped) {
   const { width, height, padding, font } = input;
+  const layoutFont = fontForDensity(font);
+  const m = metricsForDensity(density, layoutFont);
+  const drop = new Set(dropped);
   const ox = input.originX ?? 0;
   const oy = input.originY ?? 0;
   let top = oy + padding.top;
@@ -6206,87 +7269,115 @@ function computeFrame(input) {
     originX: ox,
     originY: oy,
     plot: { x: left, y: top, width: Math.max(0, right - left), height: Math.max(0, bottom - top) },
-    xLabelAngle: 0
+    xLabelAngle: 0,
+    xLabelMaxWidth: Math.max(0, right - left),
+    yLabelMaxWidth: Math.max(0, right - left),
+    legendOverflow: 0,
+    legendLabelMaxWidth: Math.max(0, right - left),
+    density,
+    dropped
   };
-  if (input.title?.text) {
-    const titleH = lineHeight(font.size.title);
+  if (input.title?.text && !drop.has("title")) {
+    const titleH = lineHeight(layoutFont.size.title);
     frame.titleRect = { x: left, y: top, width: right - left, height: titleH };
     top += titleH;
-    if (input.title.subtitle) {
-      const subH = lineHeight(font.size.small);
+    if (input.title.subtitle && !drop.has("subtitle")) {
+      const subH = lineHeight(layoutFont.size.small);
       frame.subtitleRect = { x: left, y: top, width: right - left, height: subH };
       top += subH;
     }
-    top += font.size.base;
+    top += m.titleGap;
   }
-  if (input.legend && input.legend.items.length > 0) {
+  if (input.legend && input.legend.items.length > 0 && !drop.has("legend")) {
     const pos = input.legend.position;
     const availW = right - left;
     const availH = bottom - top;
-    const block = layoutLegend(input.legend.items, pos, font, availW, availH);
+    const block = layoutLegend(input.legend.items, pos, layoutFont, m, availW, availH);
     frame.legendPosition = pos;
+    frame.legendOverflow = block.overflow;
+    frame.legendLabelMaxWidth = Math.max(
+      0,
+      block.width - m.legendPad * 2 - m.legendSwatch - m.legendSwatchGap
+    );
     if (pos === "top") {
       frame.legendRect = { x: left, y: top, width: availW, height: block.height };
-      top += block.height + font.size.base;
+      top += block.height + layoutFont.size.base;
     } else if (pos === "bottom") {
       frame.legendRect = { x: left, y: bottom - block.height, width: availW, height: block.height };
-      bottom -= block.height + font.size.base;
+      bottom -= block.height + layoutFont.size.base;
     } else if (pos === "left") {
       frame.legendRect = { x: left, y: top, width: block.width, height: availH };
-      left += block.width + font.size.base;
+      left += block.width + layoutFont.size.base;
     } else {
       frame.legendRect = { x: right - block.width, y: top, width: block.width, height: availH };
-      right -= block.width + font.size.base;
+      right -= block.width + layoutFont.size.base;
     }
-    const ox2 = frame.legendRect.x + LEGEND_PAD;
-    const oy2 = frame.legendRect.y + LEGEND_PAD;
+    const ox2 = frame.legendRect.x + m.legendPad;
+    const oy2 = frame.legendRect.y + m.legendPad;
     frame.legendItems = block.items.map((it) => ({ ...it, x: it.x + ox2, y: it.y + oy2 }));
+    if (block.overflowRow) {
+      frame.legendOverflowRect = {
+        ...block.overflowRow,
+        x: block.overflowRow.x + ox2,
+        y: block.overflowRow.y + oy2
+      };
+    }
   }
   if (input.yAxis?.show) {
     let gutter = 0;
     if (input.yAxis.labels.length) {
-      const wfont = fontString(font.size.small, font.family, font.weight.normal);
+      const wfont = fontString(layoutFont.size.small, layoutFont.family, layoutFont.weight.normal);
       const widest = Math.max(...input.yAxis.labels.map((l) => measureText(l, wfont).width));
-      gutter = Math.ceil(widest) + TICK_SIZE + AXIS_LABEL_GAP;
+      const capped = Math.min(widest, Math.max(0, (right - left) * MAX_Y_GUTTER_FRACTION));
+      frame.yLabelMaxWidth = capped;
+      gutter = Math.ceil(capped) + m.tickSize + m.axisLabelGap;
+    }
+    if (input.yAxis.title && !drop.has("axis-titles")) {
+      gutter += lineHeight(layoutFont.size.base) + m.axisTitleGap;
     }
-    if (input.yAxis.title) gutter += lineHeight(font.size.base) + AXIS_TITLE_GAP;
     left += gutter;
-    const yHalf = Math.ceil(lineHeight(font.size.small) / 2);
+    const yHalf = Math.ceil(lineHeight(layoutFont.size.small) / 2);
     top += yHalf;
     bottom -= yHalf;
   }
   if (input.y2Axis?.show) {
     let gutter = 0;
     if (input.y2Axis.labels.length) {
-      const wfont = fontString(font.size.small, font.family, font.weight.normal);
+      const wfont = fontString(layoutFont.size.small, layoutFont.family, layoutFont.weight.normal);
       const widest = Math.max(...input.y2Axis.labels.map((l) => measureText(l, wfont).width));
-      gutter = Math.ceil(widest) + TICK_SIZE + AXIS_LABEL_GAP;
+      gutter = Math.ceil(widest) + m.tickSize + m.axisLabelGap;
+    }
+    if (input.y2Axis.title && !drop.has("axis-titles")) {
+      gutter += lineHeight(layoutFont.size.base) + m.axisTitleGap;
     }
-    if (input.y2Axis.title) gutter += lineHeight(font.size.base) + AXIS_TITLE_GAP;
     right -= gutter;
     if (!input.yAxis?.show) {
-      const yHalf = Math.ceil(lineHeight(font.size.small) / 2);
+      const yHalf = Math.ceil(lineHeight(layoutFont.size.small) / 2);
       top += yHalf;
       bottom -= yHalf;
     }
   }
   if (input.xAxis?.show) {
-    const angle = resolveXLabelAngle(input.xAxis, right - left, font);
+    const angle = resolveXLabelAngle(input.xAxis, right - left, layoutFont);
     frame.xLabelAngle = angle;
-    const labelH = lineHeight(font.size.small);
+    const labelH = lineHeight(layoutFont.size.small);
     let labelBand = labelH;
+    frame.xLabelMaxWidth = Math.max(0, right - left);
     if (angle > 0 && input.xAxis.labels.length) {
-      const wfont = fontString(font.size.small, font.family, font.weight.normal);
+      const wfont = fontString(layoutFont.size.small, layoutFont.family, layoutFont.weight.normal);
       const widest = Math.max(...input.xAxis.labels.map((l) => measureText(l, wfont).width));
-      const cappedW = Math.min(widest, (bottom - top) * 0.4);
+      const cappedW = Math.min(widest, (bottom - top) * MAX_X_BAND_FRACTION);
+      frame.xLabelMaxWidth = Math.max(0, cappedW);
       const rad = angle * Math.PI / 180;
       labelBand = Math.ceil(cappedW * Math.sin(rad) + labelH * Math.cos(rad));
     }
-    let gutter = labelBand + TICK_SIZE + AXIS_LABEL_GAP;
-    if (input.xAxis.title) gutter += lineHeight(font.size.base) + AXIS_TITLE_GAP;
+    let gutter = labelBand + m.tickSize + m.axisLabelGap;
+    if (input.xAxis.title && !drop.has("axis-titles")) {
+      gutter += lineHeight(layoutFont.size.base) + m.axisTitleGap;
+    }
     bottom -= gutter;
     if (input.xAxis.edgeAnchored && angle === 0 && input.xAxis.labels.length) {
-      const wfont = fontString(font.size.small, font.family, font.weight.normal);
+      const wfont = fontString(layoutFont.size.small, layoutFont.family, layoutFont.weight.normal);
       const labels = input.xAxis.labels;
       const firstHalf = Math.ceil(measureText(labels[0], wfont).width / 2);
       const lastHalf = Math.ceil(measureText(labels[labels.length - 1], wfont).width / 2);
@@ -6302,6 +7393,22 @@ function computeFrame(input) {
   };
   return frame;
 }
+function computeFrame(input) {
+  const comfortable = computeFramePass(input, "comfortable", []);
+  const density = resolveDensity(comfortable);
+  const dropped = [];
+  let frame = density === "comfortable" ? comfortable : computeFramePass(input, density, dropped);
+  const ladder = ["subtitle", "axis-titles", "legend", "title"];
+  for (const rung of ladder) {
+    if (viable(frame.plot)) break;
+    if (rung === "subtitle" && !input.title?.subtitle || rung === "axis-titles" && !input.xAxis?.title && !input.yAxis?.title && !input.y2Axis?.title || rung === "legend" && (!input.legend || input.legend.items.length === 0) || rung === "title" && !input.title?.text) {
+      continue;
+    }
+    dropped.push(rung);
+    frame = computeFramePass(input, density, [...dropped]);
+  }
+  return frame;
+}
 
 // src/util/math.ts
 function clamp(v, min, max) {
@@ -6314,19 +7421,38 @@ function crisp(v, strokeWidth = 1) {
 
 // src/axes/draw.ts
 function addText(surface, font, o) {
+  const budget = o.maxWidth ?? o.width;
+  const fitted = fitLabel(o.text, budget, font);
+  const geom = {
+    left: o.left ?? 0,
+    top: o.top ?? 0,
+    width: o.width,
+    text: fitted.text,
+    color: o.color,
+    size: o.size,
+    align: o.align,
+    transform: o.transform
+  };
+  const { box, angle } = labelBox(geom, font);
+  recordLabel(surface.labels, {
+    role: o.role ?? "other",
+    text: fitted.text,
+    fullText: o.text,
+    truncated: fitted.truncated,
+    box,
+    angle,
+    size: o.size,
+    budget,
+    axis: o.axis
+  });
   if (surface.headless) {
-    paintCanvasText(
-      surface.marks.ctx,
-      overlayTextToCanvasCmd(
-        { left: o.left ?? 0, top: o.top ?? 0, width: o.width, text: o.text, color: o.color, size: o.size, align: o.align, transform: o.transform },
-        font
-      )
-    );
+    paintCanvasText(surface.marks.ctx, overlayTextToCanvasCmd(geom, font));
     return;
   }
   const overlay = surface.overlay;
   const el = document.createElement("div");
-  el.textContent = o.text;
+  el.textContent = fitted.text;
+  if (fitted.truncated) el.title = o.text;
   el.style.position = "absolute";
   el.style.font = font;
   el.style.fontSize = `${o.size}px`;
@@ -6492,6 +7618,19 @@ function thinXTicks(model, avgCharPx) {
   const stride = Math.ceil(needed / available);
   return ticks2.filter((_, i) => i % stride === 0);
 }
+function thinGutterTicks(ticks2, fontSize) {
+  if (ticks2.length <= 2) return ticks2;
+  const minGap = fontSize * 1.35;
+  const span = Math.abs(ticks2[ticks2.length - 1].pos - ticks2[0].pos);
+  const gap = span / (ticks2.length - 1);
+  if (gap >= minGap) return ticks2;
+  const stride = Math.ceil(minGap / Math.max(gap, 1e-6));
+  const kept = ticks2.filter((_, i) => i % stride === 0);
+  const last = ticks2[ticks2.length - 1];
+  const tail = kept[kept.length - 1];
+  if (tail !== last && Math.abs(last.pos - tail.pos) >= minGap) kept.push(last);
+  return kept;
+}
 function placeXLabels(ticks2, originX, frameWidth, font) {
   const edgePad = 2;
   const minGap = 6;
@@ -6557,7 +7696,7 @@ function drawOverlay(surface, model) {
   const gutterLabelsOn = horizontal ? model.spec.axes?.x?.labels !== false : model.spec.axes?.y?.labels !== false;
   if (gutterLabelsOn) {
     const gutterRight = plot.x - TICK_SIZE - 4;
-    for (const t of gutterTicks) {
+    for (const t of thinGutterTicks(gutterTicks, f.size.small)) {
       addText(surface, smallFont, {
         left: 0,
         top: t.pos,
@@ -6566,7 +7705,9 @@ function drawOverlay(surface, model) {
         color: tokens.color.textMuted,
         size: f.size.small,
         align: "right",
-        transform: "translateY(-50%)"
+        transform: "translateY(-50%)",
+        role: "axis-label",
+        axis: horizontal ? "x" : "y"
       });
     }
   }
@@ -6581,7 +7722,10 @@ function drawOverlay(surface, model) {
           text: p.text,
           color: tokens.color.textMuted,
           size: f.size.small,
-          transform: p.transform
+          transform: p.transform,
+          maxWidth: frame.xLabelMaxWidth,
+          role: "axis-label",
+          axis: "y"
         });
       }
     } else {
@@ -6595,7 +7739,10 @@ function drawOverlay(surface, model) {
           size: f.size.small,
           align: rotated ? "right" : void 0,
           transform: p.transform,
-          transformOrigin: rotated ? "100% 0%" : void 0
+          transformOrigin: rotated ? "100% 0%" : void 0,
+          maxWidth: frame.xLabelMaxWidth,
+          role: "axis-label",
+          axis: "x"
         });
       }
     }
@@ -6619,7 +7766,10 @@ function drawAxisTitles(surface, model) {
         color: tokens.color.text,
         size: f.size.base,
         weight: f.weight.medium,
-        transform: "translateX(-50%)"
+        transform: "translateX(-50%)",
+        maxWidth: plot.width,
+        role: "axis-title",
+        axis: "y"
       });
     }
     if (xTitle) {
@@ -6630,7 +7780,10 @@ function drawAxisTitles(surface, model) {
         color: tokens.color.text,
         size: f.size.base,
         weight: f.weight.medium,
-        transform: "translate(-50%, -50%) rotate(-90deg)"
+        transform: "translate(-50%, -50%) rotate(-90deg)",
+        maxWidth: plot.height,
+        role: "axis-title",
+        axis: "x"
       });
     }
     return;
@@ -6643,7 +7796,10 @@ function drawAxisTitles(surface, model) {
       color: tokens.color.text,
       size: f.size.base,
       weight: f.weight.medium,
-      transform: "translateX(-50%)"
+      transform: "translateX(-50%)",
+      maxWidth: plot.width,
+      role: "axis-title",
+      axis: "x"
     });
   }
   if (yTitle) {
@@ -6654,7 +7810,10 @@ function drawAxisTitles(surface, model) {
       color: tokens.color.text,
       size: f.size.base,
       weight: f.weight.medium,
-      transform: "translate(-50%, -50%) rotate(-90deg)"
+      transform: "translate(-50%, -50%) rotate(-90deg)",
+      maxWidth: plot.height,
+      role: "axis-title",
+      axis: "y"
     });
   }
 }
@@ -6672,7 +7831,8 @@ function drawTitle(surface, frame, spec, tokens) {
     color: tokens.color.text,
     size: f.size.title,
     weight: f.weight.bold,
-    align
+    align,
+    role: "title"
   });
   if (frame.subtitleRect && title2.subtitle) {
     addText(surface, fontString(f.size.small, f.family, f.weight.normal), {
@@ -6682,28 +7842,65 @@ function drawTitle(surface, frame, spec, tokens) {
       text: title2.subtitle,
       color: tokens.color.textMuted,
       size: f.size.small,
-      align
+      align,
+      role: "subtitle"
     });
   }
 }
 function drawLegend(surface, items, model) {
   const f = model.tokens.font;
+  const frame = model.frame;
   const legendFont = fontString(f.size.small, f.family, f.weight.normal);
+  const swatch = 11;
+  const budget = frame.legendLabelMaxWidth;
+  const record = (text2, full, truncated, x, midY) => {
+    recordLabel(surface.labels, {
+      role: "legend",
+      text: text2,
+      fullText: full,
+      truncated,
+      box: {
+        x,
+        y: midY - f.size.small * 0.6,
+        width: measureText(text2, legendFont).width,
+        height: f.size.small * 1.2
+      },
+      angle: 0,
+      size: f.size.small,
+      budget
+    });
+  };
+  const overflowText = frame.legendOverflow > 0 ? `+${frame.legendOverflow} more` : null;
   if (surface.headless) {
     const ctx = surface.marks.ctx;
-    const swatch = 11;
     for (const item of items) {
       const midY = item.y + swatch / 2;
+      const textX = item.x + legendSwatchWidth(item.symbol, swatch) + 6;
+      const fitted = fitLabel(item.label, budget, legendFont);
       paintLegendSwatch(ctx, item.x, midY, item.symbol, item.color, swatch);
       paintCanvasText(ctx, {
-        x: item.x + legendSwatchWidth(item.symbol, swatch) + 6,
+        x: textX,
         y: midY,
-        text: item.label,
+        text: fitted.text,
         font: legendFont,
         color: model.tokens.color.text,
         size: f.size.small,
         baseline: "middle"
       });
+      record(fitted.text, item.label, fitted.truncated, textX, midY);
+    }
+    if (overflowText && frame.legendOverflowRect) {
+      const r = frame.legendOverflowRect;
+      paintCanvasText(ctx, {
+        x: r.x,
+        y: r.y + r.height / 2,
+        text: overflowText,
+        font: legendFont,
+        color: model.tokens.color.textMuted,
+        size: f.size.small,
+        baseline: "middle"
+      });
+      record(overflowText, overflowText, false, r.x, r.y + r.height / 2);
     }
     return;
   }
@@ -6717,32 +7914,56 @@ function drawLegend(surface, items, model) {
     row.style.alignItems = "center";
     row.style.gap = "6px";
     row.style.pointerEvents = "none";
-    const swatch = document.createElement("span");
-    const size = 11;
-    swatch.style.flex = "0 0 auto";
-    swatch.style.background = item.color;
+    const swatchEl = document.createElement("span");
+    const size = swatch;
+    swatchEl.style.flex = "0 0 auto";
+    swatchEl.style.background = item.color;
     if (item.symbol === "circle") {
-      swatch.style.width = `${size}px`;
-      swatch.style.height = `${size}px`;
-      swatch.style.borderRadius = "50%";
+      swatchEl.style.width = `${size}px`;
+      swatchEl.style.height = `${size}px`;
+      swatchEl.style.borderRadius = "50%";
     } else if (item.symbol === "line") {
-      swatch.style.width = `${size + 3}px`;
-      swatch.style.height = "3px";
-      swatch.style.borderRadius = "2px";
+      swatchEl.style.width = `${size + 3}px`;
+      swatchEl.style.height = "3px";
+      swatchEl.style.borderRadius = "2px";
     } else {
-      swatch.style.width = `${size}px`;
-      swatch.style.height = `${size}px`;
-      swatch.style.borderRadius = "2px";
+      swatchEl.style.width = `${size}px`;
+      swatchEl.style.height = `${size}px`;
+      swatchEl.style.borderRadius = "2px";
     }
     const label = document.createElement("span");
-    label.textContent = item.label;
+    const fitted = fitLabel(item.label, budget, legendFont);
+    label.textContent = fitted.text;
+    if (fitted.truncated) label.title = item.label;
     label.style.font = legendFont;
     label.style.fontSize = `${f.size.small}px`;
     label.style.color = model.tokens.color.text;
     label.style.whiteSpace = "nowrap";
-    row.appendChild(swatch);
+    row.appendChild(swatchEl);
     row.appendChild(label);
     overlay.appendChild(row);
+    record(
+      fitted.text,
+      item.label,
+      fitted.truncated,
+      item.x + legendSwatchWidth(item.symbol, swatch) + 6,
+      item.y + swatch / 2
+    );
+  }
+  if (overflowText && frame.legendOverflowRect) {
+    const r = frame.legendOverflowRect;
+    const chip = document.createElement("div");
+    chip.textContent = overflowText;
+    chip.style.position = "absolute";
+    chip.style.left = `${r.x}px`;
+    chip.style.top = `${r.y}px`;
+    chip.style.font = legendFont;
+    chip.style.fontSize = `${f.size.small}px`;
+    chip.style.color = model.tokens.color.textMuted;
+    chip.style.whiteSpace = "nowrap";
+    chip.style.pointerEvents = "none";
+    overlay.appendChild(chip);
+    record(overflowText, overflowText, false, r.x, r.y + r.height / 2);
   }
 }
 
@@ -7324,8 +8545,8 @@ function buildXModel(kind, args) {
     };
   }
   const domain = args.domainNum ?? [0, 1];
-  const clamp11 = args.scaleCfg?.clamp === true;
-  const continuous = kind === "time" ? timeScale({ domain, range: args.range }) : args.scaleCfg?.type === "log" ? logScale({ domain, range: args.range, base: args.scaleCfg.base ?? 10, clamp: clamp11 }) : linearScale({ domain, range: args.range, clamp: clamp11 });
+  const clamp16 = args.scaleCfg?.clamp === true;
+  const continuous = kind === "time" ? timeScale({ domain, range: args.range }) : args.scaleCfg?.type === "log" ? logScale({ domain, range: args.range, base: args.scaleCfg.base ?? 10, clamp: clamp16 }) : linearScale({ domain, range: args.range, clamp: clamp16 });
   return {
     kind,
     field: args.field,
@@ -7776,6 +8997,27 @@ function drawArea(surface, model) {
 function finite2(value) {
   return Number.isFinite(value);
 }
+function readableWithin(text2, maxWidth, font) {
+  if (maxWidth <= 0) return false;
+  if (measureText(text2, font).width <= maxWidth) return true;
+  return ellipsize(text2, maxWidth, font).length / Math.max(1, text2.length) >= 0.5;
+}
+function prepareAxisLabels(model) {
+  if (model.x.kind !== "band" || model.xTicks.length <= 1) return;
+  const { font, spacing } = model.tokens;
+  const smallFont = fontString(font.size.small, font.family, font.weight.normal);
+  const budget = Math.max(0, model.frame.xLabelMaxWidth);
+  const originalCount = model.xTicks.length;
+  model.xTicks = model.xTicks.filter((t) => readableWithin(t.label, budget, smallFont));
+  if (model.orientation !== "horizontal") model.frame.xLabelAngle = 0;
+  const widest = model.xTicks.reduce((m, t) => Math.max(m, measureText(t.label, smallFont).width), 0);
+  const slot = model.plot.width / Math.max(1, model.xTicks.length);
+  const crowding = originalCount > 30 ? 2 : 1;
+  const minStep = Math.max(font.size.small * 1.35, widest * crowding + spacing.sm);
+  if (slot >= minStep) return;
+  const stride = Math.ceil(minStep / Math.max(slot, 1e-6));
+  model.xTicks = model.xTicks.filter((_, i) => i % stride === 0);
+}
 function defaultRadius(model, spec) {
   return Math.max(0, spec.cornerRadius ?? Math.min(4, model.tokens.radius.sm));
 }
@@ -7895,6 +9137,7 @@ function drawBar(surface, model) {
   const radius = defaultRadius(model, spec);
   const pen = model.sketch ? new RoughPen(ctx, model.sketch) : null;
   if (model.x.kind !== "band" || model.x.bandwidth <= 0 || model.series.length === 0) return;
+  prepareAxisLabels(model);
   ctx.save();
   ctx.beginPath();
   ctx.rect(plot.x, plot.y, plot.width, plot.height);
@@ -7908,6 +9151,25 @@ function drawBar(surface, model) {
 }
 
 // src/charts/box.ts
+function readableWithin2(text2, maxWidth, font) {
+  if (maxWidth <= 0) return false;
+  if (measureText(text2, font).width <= maxWidth) return true;
+  return ellipsize(text2, maxWidth, font).length / Math.max(1, text2.length) >= 0.5;
+}
+function prepareAxisLabels2(model) {
+  if (model.x.kind !== "band" || model.xTicks.length <= 1) return;
+  const { font, spacing } = model.tokens;
+  const smallFont = fontString(font.size.small, font.family, font.weight.normal);
+  const budget = Math.max(0, model.frame.xLabelMaxWidth);
+  model.xTicks = model.xTicks.filter((t) => readableWithin2(t.label, budget, smallFont));
+  model.frame.xLabelAngle = 0;
+  const widest = model.xTicks.reduce((m, t) => Math.max(m, measureText(t.label, smallFont).width), 0);
+  const slot = model.plot.width / Math.max(1, model.xTicks.length);
+  const minStep = Math.max(font.size.small * 1.35, widest + spacing.sm);
+  if (slot >= minStep) return;
+  const stride = Math.ceil(minStep / Math.max(slot, 1e-6));
+  model.xTicks = model.xTicks.filter((_, i) => i % stride === 0);
+}
 function quantileSorted(sorted, p) {
   const n = sorted.length;
   if (n === 0) return NaN;
@@ -8075,6 +9337,7 @@ function hitsBoxGeom(model, geom, showOutliers, px, py) {
 function drawBox(surface, model) {
   const layout2 = computeBoxes(model);
   if (!layout2) return;
+  prepareAxisLabels2(model);
   const ctx = surface.marks.ctx;
   const { plot } = model;
   const emphasis = model.emphasis ?? null;
@@ -8162,29 +9425,38 @@ function resolveTitle2(title2) {
 }
 function addOverlayText(surface, tokens, o) {
   const font = fontString(o.size, tokens.font.family, o.weight ?? tokens.font.weight.normal);
+  const budget = o.maxWidth ?? o.width;
+  const fitted = fitLabel(o.text, budget, font);
+  const geom = {
+    left: o.left,
+    top: o.top,
+    width: o.width,
+    text: fitted.text,
+    color: o.color,
+    size: o.size,
+    align: o.align,
+    transform: o.transform,
+    opacity: o.opacity,
+    pill: o.pill
+  };
+  const { box, angle } = labelBox(geom, font);
+  recordLabel(surface.labels, {
+    role: o.role ?? "data-label",
+    text: fitted.text,
+    fullText: o.text,
+    truncated: fitted.truncated,
+    box,
+    angle,
+    size: o.size,
+    budget
+  });
   if (surface.headless) {
-    paintCanvasText(
-      surface.marks.ctx,
-      overlayTextToCanvasCmd(
-        {
-          left: o.left,
-          top: o.top,
-          width: o.width,
-          text: o.text,
-          color: o.color,
-          size: o.size,
-          align: o.align,
-          transform: o.transform,
-          opacity: o.opacity,
-          pill: o.pill
-        },
-        font
-      )
-    );
+    paintCanvasText(surface.marks.ctx, overlayTextToCanvasCmd(geom, font));
     return null;
   }
   const el = document.createElement("div");
-  el.textContent = o.text;
+  el.textContent = fitted.text;
+  if (fitted.truncated) el.title = o.text;
   el.style.position = "absolute";
   el.style.font = font;
   el.style.color = o.color;
@@ -8224,7 +9496,8 @@ function drawTitleBlock(surface, tokens, size, title2) {
       color: tokens.color.text,
       size: f.size.title,
       weight: f.weight.bold,
-      align: t.align
+      align: t.align,
+      role: "title"
     });
     top += Math.round(f.size.title * 1.3);
     if (t.subtitle) {
@@ -8235,7 +9508,8 @@ function drawTitleBlock(surface, tokens, size, title2) {
         text: t.subtitle,
         color: tokens.color.textMuted,
         size: f.size.small,
-        align: t.align
+        align: t.align,
+        role: "subtitle"
       });
       top += Math.round(f.size.small * 1.5);
     } else {
@@ -8249,139 +9523,164 @@ function drawTitleBlock(surface, tokens, size, title2) {
     height: Math.max(0, size.height - top - CHROME_PAD.bottom)
   };
 }
+var MAX_LEGEND_WIDTH_FRACTION2 = 0.3;
+var LEGEND_SWATCH3 = 11;
+var LEGEND_LABEL_GAP = 6;
+var LEGEND_ITEM_GAP2 = 16;
+var LEGEND_ROW_GAP2 = 4;
+function paintLegendRow(surface, tokens, font, labelSize, row) {
+  const symbol = row.entry?.symbol;
+  const textX = row.entry ? row.x + legendSwatchWidth(symbol, LEGEND_SWATCH3) + LEGEND_LABEL_GAP : row.x;
+  if (surface.headless) {
+    const ctx = surface.marks.ctx;
+    if (row.entry) paintLegendSwatch(ctx, row.x, row.midY, symbol, row.entry.color, LEGEND_SWATCH3);
+    paintCanvasText(ctx, {
+      x: textX,
+      y: row.midY,
+      text: row.text,
+      font,
+      color: row.color,
+      size: labelSize,
+      baseline: "middle"
+    });
+  } else {
+    const el = document.createElement("div");
+    el.style.position = "absolute";
+    el.style.left = `${row.x}px`;
+    el.style.top = `${row.midY - LEGEND_SWATCH3 / 2}px`;
+    el.style.height = `${LEGEND_SWATCH3}px`;
+    el.style.display = "flex";
+    el.style.alignItems = "center";
+    el.style.gap = `${LEGEND_LABEL_GAP}px`;
+    el.style.pointerEvents = "none";
+    if (row.entry) {
+      const s = document.createElement("span");
+      s.style.flex = "0 0 auto";
+      s.style.background = row.entry.color;
+      if (symbol === "line") {
+        s.style.width = `${LEGEND_SWATCH3 + 3}px`;
+        s.style.height = "3px";
+        s.style.borderRadius = "2px";
+      } else {
+        s.style.width = `${LEGEND_SWATCH3}px`;
+        s.style.height = `${LEGEND_SWATCH3}px`;
+        s.style.borderRadius = symbol === "circle" ? "50%" : "2px";
+      }
+      el.appendChild(s);
+    }
+    const label = document.createElement("span");
+    label.textContent = row.text;
+    if (row.truncated) label.title = row.fullText;
+    label.style.font = font;
+    label.style.color = row.color;
+    label.style.whiteSpace = "nowrap";
+    el.appendChild(label);
+    surface.overlay.appendChild(el);
+  }
+  recordLabel(surface.labels, {
+    role: "legend",
+    text: row.text,
+    fullText: row.fullText,
+    truncated: row.truncated,
+    box: {
+      x: textX,
+      y: row.midY - labelSize * 0.6,
+      width: measureText(row.text, font).width,
+      height: labelSize * 1.2
+    },
+    angle: 0,
+    size: labelSize,
+    budget: row.budget
+  });
+}
 function drawCategoricalLegend(surface, tokens, area2, entries, position = "right") {
   if (entries.length === 0) return area2;
   const f = tokens.font;
   const labelSize = f.size.small;
   const rowH = Math.round(labelSize * 1.7);
-  const swatch = 11;
-  const gap = 16;
   const font = fontString(labelSize, f.family, f.weight.normal);
-  if (surface.headless) {
-    const ctx = surface.marks.ctx;
-    if (position === "right") {
-      let maxLabel = 0;
-      for (const e of entries) maxLabel = Math.max(maxLabel, measureText(e.label, font).width);
-      const colW = Math.ceil(swatch + 6 + maxLabel + 4);
-      const x = area2.x + area2.width - colW;
-      let y = area2.y + Math.max(0, (area2.height - entries.length * rowH) / 2);
-      for (const e of entries) {
-        const midY2 = y + rowH / 2;
-        paintLegendSwatch(ctx, x, midY2, e.symbol, e.color, swatch);
-        paintCanvasText(ctx, {
-          x: x + legendSwatchWidth(e.symbol, swatch) + 6,
-          y: midY2,
-          text: e.label,
-          font,
-          color: tokens.color.text,
-          size: labelSize,
-          baseline: "middle"
-        });
-        y += rowH;
-      }
-      return { x: area2.x, y: area2.y, width: Math.max(0, area2.width - colW - gap), height: area2.height };
-    }
-    const widths = entries.map(
-      (e) => legendSwatchWidth(e.symbol, swatch) + 6 + measureText(e.label, font).width
-    );
-    const total = widths.reduce((a, b) => a + b, 0) + gap * Math.max(0, entries.length - 1);
-    let cx = area2.x + Math.max(0, (area2.width - total) / 2);
-    const barH2 = rowH;
-    const barTop = position === "top" ? area2.y : area2.y + area2.height - barH2;
-    const midY = barTop + barH2 / 2;
-    entries.forEach((e, i) => {
-      paintLegendSwatch(ctx, cx, midY, e.symbol, e.color, swatch);
-      paintCanvasText(ctx, {
-        x: cx + legendSwatchWidth(e.symbol, swatch) + 6,
-        y: midY,
-        text: e.label,
-        font,
-        color: tokens.color.text,
-        size: labelSize,
-        baseline: "middle"
-      });
-      cx += widths[i] + gap;
-    });
-    return position === "top" ? { x: area2.x, y: area2.y + barH2 + 6, width: area2.width, height: Math.max(0, area2.height - barH2 - 6) } : { x: area2.x, y: area2.y, width: area2.width, height: Math.max(0, area2.height - barH2 - 6) };
-  }
-  const makeSwatch = (e) => {
-    const s = document.createElement("span");
-    s.style.flex = "0 0 auto";
-    s.style.background = e.color;
-    if (e.symbol === "line") {
-      s.style.width = `${swatch + 3}px`;
-      s.style.height = "3px";
-      s.style.borderRadius = "2px";
-    } else if (e.symbol === "circle") {
-      s.style.width = `${swatch}px`;
-      s.style.height = `${swatch}px`;
-      s.style.borderRadius = "50%";
-    } else {
-      s.style.width = `${swatch}px`;
-      s.style.height = `${swatch}px`;
-      s.style.borderRadius = "2px";
-    }
-    return s;
-  };
+  const swatchFor = (e) => legendSwatchWidth(e.symbol, LEGEND_SWATCH3) + LEGEND_LABEL_GAP;
   if (position === "right") {
+    const cap2 = Math.max(0, area2.width * MAX_LEGEND_WIDTH_FRACTION2);
+    const maxRows = Math.max(1, Math.floor(area2.height / rowH));
+    const overflowing = entries.length > maxRows;
+    const shown = overflowing ? entries.slice(0, Math.max(0, maxRows - 1)) : entries;
+    const overflow = entries.length - shown.length;
+    const budget2 = Math.max(0, cap2 - LEGEND_SWATCH3 - 3 - LEGEND_LABEL_GAP);
+    const fitted2 = shown.map((e) => ({ entry: e, ...fitLabel(e.label, budget2, font) }));
+    const overflowText = overflow > 0 ? `+${overflow} more` : null;
     let maxLabel = 0;
-    for (const e of entries) maxLabel = Math.max(maxLabel, measureText(e.label, font).width);
-    const colW = Math.ceil(swatch + 6 + maxLabel + 4);
+    for (const it of fitted2) maxLabel = Math.max(maxLabel, measureText(it.text, font).width);
+    if (overflowText) maxLabel = Math.max(maxLabel, measureText(overflowText, font).width);
+    const colW = Math.ceil(LEGEND_SWATCH3 + LEGEND_LABEL_GAP + maxLabel + 4);
     const x = area2.x + area2.width - colW;
-    let y = area2.y + Math.max(0, (area2.height - entries.length * rowH) / 2);
-    for (const e of entries) {
-      const row = document.createElement("div");
-      row.style.position = "absolute";
-      row.style.left = `${x}px`;
-      row.style.top = `${y}px`;
-      row.style.display = "flex";
-      row.style.alignItems = "center";
-      row.style.gap = "6px";
-      row.style.pointerEvents = "none";
-      const label = document.createElement("span");
-      label.textContent = e.label;
-      label.style.font = font;
-      label.style.color = tokens.color.text;
-      label.style.whiteSpace = "nowrap";
-      row.appendChild(makeSwatch(e));
-      row.appendChild(label);
-      surface.overlay.appendChild(row);
+    const rows2 = fitted2.length + (overflowText ? 1 : 0);
+    let y = area2.y + Math.max(0, (area2.height - rows2 * rowH) / 2);
+    for (const it of fitted2) {
+      paintLegendRow(surface, tokens, font, labelSize, {
+        x,
+        midY: y + rowH / 2,
+        text: it.text,
+        fullText: it.entry.label,
+        truncated: it.truncated,
+        budget: budget2,
+        color: tokens.color.text,
+        entry: it.entry
+      });
       y += rowH;
     }
-    return { x: area2.x, y: area2.y, width: Math.max(0, area2.width - colW - gap), height: area2.height };
-  }
-  const bar = document.createElement("div");
-  bar.style.position = "absolute";
-  bar.style.left = `${area2.x}px`;
-  bar.style.width = `${area2.width}px`;
-  bar.style.display = "flex";
-  bar.style.flexWrap = "wrap";
-  bar.style.justifyContent = "center";
-  bar.style.gap = `4px ${gap}px`;
-  bar.style.pointerEvents = "none";
-  for (const e of entries) {
-    const row = document.createElement("div");
-    row.style.display = "flex";
-    row.style.alignItems = "center";
-    row.style.gap = "6px";
-    const label = document.createElement("span");
-    label.textContent = e.label;
-    label.style.font = font;
-    label.style.color = tokens.color.text;
-    label.style.whiteSpace = "nowrap";
-    row.appendChild(makeSwatch(e));
-    row.appendChild(label);
-    bar.appendChild(row);
-  }
-  const barH = rowH;
-  if (position === "top") {
-    bar.style.top = `${area2.y}px`;
-    surface.overlay.appendChild(bar);
-    return { x: area2.x, y: area2.y + barH + 6, width: area2.width, height: Math.max(0, area2.height - barH - 6) };
+    if (overflowText) {
+      paintLegendRow(surface, tokens, font, labelSize, {
+        x,
+        midY: y + rowH / 2,
+        text: overflowText,
+        fullText: overflowText,
+        truncated: false,
+        budget: budget2,
+        color: tokens.color.textMuted
+      });
+    }
+    return {
+      x: area2.x,
+      y: area2.y,
+      width: Math.max(0, area2.width - colW - LEGEND_ITEM_GAP2),
+      height: area2.height
+    };
   }
-  bar.style.top = `${area2.y + area2.height - barH}px`;
-  surface.overlay.appendChild(bar);
-  return { x: area2.x, y: area2.y, width: area2.width, height: Math.max(0, area2.height - barH - 6) };
+  const budget = Math.max(0, area2.width - LEGEND_SWATCH3 - 3 - LEGEND_LABEL_GAP);
+  const fitted = entries.map((e) => ({ entry: e, ...fitLabel(e.label, budget, font) }));
+  const widths = fitted.map((it) => swatchFor(it.entry) + measureText(it.text, font).width);
+  const rows = [{ items: [], width: 0 }];
+  widths.forEach((w, i) => {
+    const row = rows[rows.length - 1];
+    if (row.items.length && row.width + LEGEND_ITEM_GAP2 + w > area2.width) {
+      rows.push({ items: [i], width: w });
+    } else {
+      row.width += (row.items.length ? LEGEND_ITEM_GAP2 : 0) + w;
+      row.items.push(i);
+    }
+  });
+  const barH = rows.length * rowH + (rows.length - 1) * LEGEND_ROW_GAP2;
+  const barTop = position === "top" ? area2.y : area2.y + area2.height - barH;
+  rows.forEach((row, r) => {
+    let cx = area2.x + Math.max(0, (area2.width - row.width) / 2);
+    const midY = barTop + r * (rowH + LEGEND_ROW_GAP2) + rowH / 2;
+    for (const i of row.items) {
+      const it = fitted[i];
+      paintLegendRow(surface, tokens, font, labelSize, {
+        x: cx,
+        midY,
+        text: it.text,
+        fullText: it.entry.label,
+        truncated: it.truncated,
+        budget,
+        color: tokens.color.text,
+        entry: it.entry
+      });
+      cx += widths[i] + LEGEND_ITEM_GAP2;
+    }
+  });
+  return position === "top" ? { x: area2.x, y: area2.y + barH + 6, width: area2.width, height: Math.max(0, area2.height - barH - 6) } : { x: area2.x, y: area2.y, width: area2.width, height: Math.max(0, area2.height - barH - 6) };
 }
 
 // src/charts/heatmap.ts
@@ -8401,6 +9700,11 @@ function measureMax(labels, font) {
   for (const label of labels) max = Math.max(max, measureText(label, font).width);
   return max;
 }
+function readableWithin3(text2, maxWidth, font) {
+  if (maxWidth <= 0) return false;
+  if (measureText(text2, font).width <= maxWidth) return true;
+  return ellipsize(text2, maxWidth, font).length / Math.max(1, text2.length) >= 0.5;
+}
 function heatmapColorDomain(rows, field) {
   const read = accessor(field);
   let min = Infinity;
@@ -8437,21 +9741,33 @@ function drawLegend2(surface, tokens, legend, min, max, spec) {
   ctx.lineWidth = 1;
   ctx.strokeRect(barX + 0.5, barY + 0.5, Math.max(0, barWidth - 1), Math.max(0, barHeight - 1));
   const labelTop = barY + barHeight + 3;
-  addOverlayText(surface, tokens, {
-    left: barX,
-    top: labelTop,
-    text: formatValue(min, spec.encoding.color.format),
-    color: tokens.color.textMuted,
-    size: tokens.font.size.small
-  });
-  addOverlayText(surface, tokens, {
-    left: barX + barWidth,
-    top: labelTop,
-    text: formatValue(max, spec.encoding.color.format),
-    color: tokens.color.textMuted,
-    size: tokens.font.size.small,
-    transform: "translateX(-100%)"
-  });
+  const labelBudget = Math.max(0, barWidth / 2 - 4);
+  const labelFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
+  const minLabel = formatValue(min, spec.encoding.color.format);
+  const maxLabel = formatValue(max, spec.encoding.color.format);
+  if (readableWithin3(minLabel, labelBudget, labelFont)) {
+    addOverlayText(surface, tokens, {
+      left: barX,
+      top: labelTop,
+      text: minLabel,
+      color: tokens.color.textMuted,
+      size: tokens.font.size.small,
+      maxWidth: labelBudget,
+      role: "legend"
+    });
+  }
+  if (readableWithin3(maxLabel, labelBudget, labelFont)) {
+    addOverlayText(surface, tokens, {
+      left: barX + barWidth,
+      top: labelTop,
+      text: maxLabel,
+      color: tokens.color.textMuted,
+      size: tokens.font.size.small,
+      transform: "translateX(-100%)",
+      maxWidth: labelBudget,
+      role: "legend"
+    });
+  }
 }
 function drawHeatmap(surface, spec, tokens, size, context) {
   const heatmap = spec;
@@ -8524,19 +9840,28 @@ function drawHeatmap(surface, spec, tokens, size, context) {
     ctx.lineWidth = 1;
     ctx.strokeRect(grid.x + 0.5, grid.y + 0.5, Math.max(0, grid.width - 1), Math.max(0, grid.height - 1));
   }
+  const yLabelBudget = Math.max(0, leftGutter - tokens.spacing.sm);
+  const yLabelMinGap = labelSize * 1.35;
+  let lastYLabelMid = -Infinity;
   for (const cat of yCats) {
     const sy = yScale.map(cat);
     if (sy === void 0) continue;
+    const mid = sy + yScale.bandwidth / 2;
+    if (mid - lastYLabelMid < yLabelMinGap) continue;
+    if (!readableWithin3(cat, yLabelBudget, labelFont)) continue;
     addOverlayText(surface, tokens, {
       left: content.x,
-      top: sy + yScale.bandwidth / 2,
-      width: Math.max(0, leftGutter - tokens.spacing.sm),
+      top: mid,
+      width: yLabelBudget,
       text: cat,
       color: tokens.color.textMuted,
       size: labelSize,
       align: "right",
-      transform: "translateY(-50%)"
+      transform: "translateY(-50%)",
+      maxWidth: yLabelBudget,
+      role: "axis-label"
     });
+    lastYLabelMid = mid;
   }
   const widestX = measureMax(xCats, labelFont);
   const every = Math.max(1, Math.ceil((widestX + tokens.spacing.md) / Math.max(1, xScale.step)));
@@ -8545,13 +9870,17 @@ function drawHeatmap(surface, spec, tokens, size, context) {
     if (index % every !== 0) return;
     const sx = xScale.map(cat);
     if (sx === void 0) return;
+    const maxWidth = Math.max(0, Math.min(xScale.step - tokens.spacing.xs, size.width - 4));
+    if (!readableWithin3(cat, maxWidth, labelFont)) return;
     addOverlayText(surface, tokens, {
       left: sx + xScale.bandwidth / 2,
       top: xLabelTop,
       text: cat,
       color: tokens.color.textMuted,
       size: labelSize,
-      transform: "translateX(-50%)"
+      transform: "translateX(-50%)",
+      maxWidth,
+      role: "axis-label"
     });
   });
   drawLegend2(
@@ -8712,6 +10041,21 @@ function planPieLabels(options) {
       const fitsRadial = lineHeight2 * 0.8 <= radialBand;
       goesInside = fitsTangential && fitsRadial;
     }
+    if (outsideSlices.length > 0) {
+      const top2 = area2.y + lineHeight2 * 1.25;
+      const bottom2 = area2.y + area2.height - lineHeight2 * 1.25;
+      const capacity = Math.max(1, Math.floor((bottom2 - top2 + lineHeight2) / lineHeight2));
+      for (const side of ["left", "right"]) {
+        const group = outsideSlices.filter((o) => o.side === side);
+        if (group.length <= capacity) continue;
+        const keep = new Set(
+          [...group].sort((a, b) => b.slice.value - a.slice.value || a.slice.index - b.slice.index).slice(0, capacity).map((o) => o.slice.index)
+        );
+        for (let i = outsideSlices.length - 1; i >= 0; i -= 1) {
+          if (outsideSlices[i].side === side && !keep.has(outsideSlices[i].slice.index)) outsideSlices.splice(i, 1);
+        }
+      }
+    }
     if (goesInside) {
       insideSlices.push({ slice, mid, text: labelText(slice, "inside", options, percents) });
     } else {
@@ -8749,13 +10093,14 @@ function planPieLabels(options) {
     cx = (leftBound + rightBound) / 2;
   }
   const insideR = innerR > 0 ? (innerR + outerR) / 2 : outerR * 0.62;
-  const inside2 = insideSlices.map(({ slice, mid, text }) => {
+  const inside2 = insideSlices.map(({ slice, mid, text: text2 }) => {
     const dir = direction(mid);
-    return { index: slice.index, text, x: cx + insideR * dir.x, y: cy + insideR * dir.y };
-  });
+    const arcWidth = Math.max(8, (slice.endAngle - slice.startAngle) * insideR - INSIDE_PAD);
+    return { index: slice.index, text: text2, maxWidth: arcWidth, x: cx + insideR * dir.x, y: cy + insideR * dir.y };
+  }).filter((label) => measure(label.text) <= label.maxWidth);
   const elbowR = outerR + ELBOW;
-  const top = area2.y + lineHeight2 / 2;
-  const bottom = area2.y + area2.height - lineHeight2 / 2;
+  const top = area2.y + lineHeight2 * 1.25;
+  const bottom = area2.y + area2.height - lineHeight2 * 1.25;
   const outside = [];
   for (const side of ["left", "right"]) {
     const group = outsideSlices.filter((o) => o.side === side);
@@ -8768,11 +10113,14 @@ function planPieLabels(options) {
       const elbow = { x: cx + elbowR * dir.x, y: cy + elbowR * dir.y };
       const labelY = ys[i];
       const textX = side === "right" ? elbow.x + GAP : elbow.x - GAP;
+      const maxWidth = side === "right" ? Math.max(0, area2.x + area2.width - textX) : Math.max(0, textX - area2.x);
+      if (maxWidth < 8 || measure(o.text) > maxWidth) return;
       outside.push({
         index: o.slice.index,
         text: o.text,
         x: textX,
         y: labelY,
+        maxWidth,
         align: side === "right" ? "left" : "right",
         side,
         points: [anchor, elbow, { x: textX, y: labelY }]
@@ -8887,8 +10235,12 @@ function drawPie(surface, spec, tokens, size, context) {
   const sweepEnd = TAU3 * sweepT;
   const content = drawTitleBlock(surface, tokens, size, pie.title);
   const slices = buildSlices(pie, tokens.color.palette);
-  const legendPosition = resolveLegendPosition(pie, content.width, content.height);
-  const area2 = legendPosition ? drawCategoricalLegend(surface, tokens, content, uniqueLegendEntries(slices), legendPosition) : content;
+  const labelCfg = resolvePieLabels(pie);
+  const labelFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
+  const legendEntries = uniqueLegendEntries(slices);
+  const suppressAutoLegend = labelCfg && pie.legend == null && legendEntries.some((entry) => measureText(entry.label, labelFont).width > content.width * 0.25);
+  const legendPosition = suppressAutoLegend ? null : resolveLegendPosition(pie, content.width, content.height);
+  const area2 = legendPosition ? drawCategoricalLegend(surface, tokens, content, legendEntries, legendPosition) : content;
   const initialCx = area2.x + area2.width / 2;
   const initialCy = area2.y + area2.height / 2;
   const initialOuterR = Math.max(0, Math.min(area2.width, area2.height) / 2 * 0.92);
@@ -8908,8 +10260,6 @@ function drawPie(surface, spec, tokens, size, context) {
     });
     return;
   }
-  const labelCfg = resolvePieLabels(pie);
-  const labelFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
   const labelPlan = labelCfg && planPieLabels({
     slices: slices.map((s, i) => ({
       index: i,
@@ -8998,7 +10348,8 @@ function drawPie(surface, spec, tokens, size, context) {
         size: tokens.font.size.small,
         transform: o.align === "right" ? "translate(-100%,-50%)" : "translateY(-50%)",
         opacity: alpha === 1 ? void 0 : alpha,
-        pill: { background: tokens.color.surface, border: tokens.color.border, padX: 6 }
+        pill: { background: tokens.color.surface, border: tokens.color.border, padX: 6 },
+        maxWidth: o.maxWidth
       });
     }
     for (const l of labelPlan.inside) {
@@ -9013,18 +10364,21 @@ function drawPie(surface, spec, tokens, size, context) {
         weight: tokens.font.weight.bold,
         transform: "translate(-50%,-50%)",
         opacity: alpha === 1 ? void 0 : alpha,
-        pill: { background: tokens.color.surface, border: tokens.color.border, padX: 6 }
+        pill: { background: tokens.color.surface, border: tokens.color.border, padX: 6 },
+        maxWidth: l.maxWidth
       });
     }
   }
   if (sweepT >= 1 && innerRadius >= 34) {
+    const centerBudget = innerRadius * 1.7;
     addOverlayText(surface, tokens, {
       left: cx,
       top: cy - tokens.font.size.small - 2,
       text: pie.encoding.theta.title ?? "Total",
       color: tokens.color.textMuted,
       size: tokens.font.size.tiny,
-      transform: "translate(-50%,-50%)"
+      transform: "translate(-50%,-50%)",
+      maxWidth: centerBudget
     });
     addOverlayText(surface, tokens, {
       left: cx,
@@ -9033,7 +10387,8 @@ function drawPie(surface, spec, tokens, size, context) {
       color: tokens.color.text,
       size: tokens.font.size.large,
       weight: tokens.font.weight.bold,
-      transform: "translate(-50%,-50%)"
+      transform: "translate(-50%,-50%)",
+      maxWidth: centerBudget
     });
   }
   if (!pieTooltipEnabled(pie)) return;
@@ -9133,6 +10488,30 @@ function buildStages(spec, palette) {
 function safeRatio(numerator, denominator) {
   return Number.isFinite(numerator) && Number.isFinite(denominator) && denominator !== 0 ? numerator / denominator : 0;
 }
+function clamp5(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function spreadCenters(ideal, minGap, top, bottom) {
+  const ordered = ideal.map((y, i) => ({ i, y })).sort((a, b) => a.y - b.y);
+  for (let i = 1; i < ordered.length; i += 1) {
+    if (ordered[i].y < ordered[i - 1].y + minGap) ordered[i].y = ordered[i - 1].y + minGap;
+  }
+  const last = ordered[ordered.length - 1];
+  if (last && last.y > bottom) {
+    const shift = last.y - bottom;
+    for (const item of ordered) item.y -= shift;
+  }
+  if (ordered.length && ordered[0].y < top) {
+    let prev = top - minGap;
+    for (const item of ordered) {
+      item.y = Math.max(item.y, prev + minGap);
+      prev = item.y;
+    }
+  }
+  const out = new Array(ideal.length);
+  for (const item of ordered) out[item.i] = item.y;
+  return out;
+}
 function funnelPercents(stages, mode = "first") {
   return stages.map((stage, i) => {
     if (mode === "previous") return i === 0 ? 1 : safeRatio(stage.value, stages[i - 1].value);
@@ -9215,33 +10594,57 @@ function drawFunnel(surface, spec, tokens, size, context) {
     return band.topHalf + (band.botHalf - band.topHalf) * t;
   };
   if (showLabels) {
+    const rowGap = 2;
+    const valueFont = fontString(tokens.font.size.tiny, tokens.font.family, tokens.font.weight.normal);
+    const labelBlockH = tokens.font.size.small * 1.2 + rowGap + tokens.font.size.tiny * 1.2;
+    const capacity = Math.max(1, Math.floor(content.height / Math.max(labelBlockH, tokens.font.size.small * 1.2)));
+    const labelBudget = Math.max(0, labelW - 8);
+    const candidates = stages.map((stage, i) => ({ i, value: stage.value })).filter(
+      ({ i }) => labelBudget >= 8 && measureText(stages[i].label, labelFont).width <= labelBudget && measureText(formatValue(stages[i].value, valueFormat), valueFont).width <= labelBudget
+    );
+    const labelled = new Set(
+      (candidates.length <= capacity ? candidates.map((item) => item.i) : candidates.sort((a, b) => b.value - a.value || a.i - b.i).slice(0, capacity).map((item) => item.i)).sort((a, b) => a - b)
+    );
+    const labelOrder = [...labelled];
+    const labelYs = spreadCenters(
+      labelOrder.map((i) => (bands[i].top + bands[i].bottom) / 2),
+      labelBlockH,
+      content.y + labelBlockH / 2,
+      content.y + content.height - labelBlockH / 2
+    );
+    const labelYByIndex = new Map(labelOrder.map((i, k) => [i, labelYs[k]]));
     for (let i = 0; i < n; i++) {
+      if (!labelled.has(i)) continue;
       const s = stages[i];
       const band = bands[i];
-      const midY = (band.top + band.bottom) / 2;
+      const bandMidY = (band.top + band.bottom) / 2;
+      const midY = labelYByIndex.get(i) ?? bandMidY;
       const dim = alphaOf(s) !== 1;
+      const labelTop = clamp5(midY - labelBlockH / 2, content.y, content.y + content.height - labelBlockH);
       addOverlayText(surface, tokens, {
         left: content.x,
-        top: midY - tokens.font.size.small,
+        top: labelTop,
         text: s.label,
         color: tokens.color.text,
         size: tokens.font.size.small,
         weight: tokens.font.weight.bold,
-        opacity: dim ? 0.5 : 1
+        opacity: dim ? 0.5 : 1,
+        maxWidth: labelBudget
       });
       addOverlayText(surface, tokens, {
         left: content.x,
-        top: midY + 2,
+        top: labelTop + tokens.font.size.small * 1.2 + rowGap,
         text: formatValue(s.value, valueFormat),
         color: tokens.color.textMuted,
         size: tokens.font.size.tiny,
-        opacity: dim ? 0.5 : 1
+        opacity: dim ? 0.5 : 1,
+        maxWidth: labelBudget
       });
       const pct = pctOf(i);
       const pctText2 = `${Math.round(pct * 100)}%`;
       const padX = 7;
       const badgeW = Math.ceil(measureText(pctText2, labelFont).width) + padX * 2 + 2;
-      const innerHalf = halfAtY(band, midY);
+      const innerHalf = halfAtY(band, bandMidY);
       const fitsInside = badgeW + 8 <= innerHalf * 2;
       let badgeLeft = cx;
       let badgeTransform = "translate(-50%,-50%)";
@@ -9260,7 +10663,8 @@ function drawFunnel(surface, spec, tokens, size, context) {
         weight: tokens.font.weight.bold,
         opacity: dim ? 0.55 : 1,
         transform: badgeTransform,
-        pill: { background: tokens.color.surface, border: tokens.color.border, padX }
+        pill: { background: tokens.color.surface, border: tokens.color.border, padX },
+        maxWidth: badgeW
       });
     }
   }
@@ -9302,7 +10706,7 @@ function drawFunnel(surface, spec, tokens, size, context) {
 
 // src/charts/kpi.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
-function clamp5(value, min, max) {
+function clamp6(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 function valueField(ref) {
@@ -9336,7 +10740,7 @@ function valueFontSize(rect, contentWidth, valueText, unit, isRich) {
   const sizeByText = contentWidth / Math.max(1, effectiveLen * 0.58);
   const lo = isRich ? 22 : 26;
   const hi = isRich ? 52 : 76;
-  return clamp5(Math.min(sizeByCard, sizeByText), lo, hi);
+  return clamp6(Math.min(sizeByCard, sizeByText), lo, hi);
 }
 function unitFontSize(valueSize) {
   return Math.max(12, valueSize * 0.46);
@@ -9374,12 +10778,12 @@ function resolveComparison(cmp, data, parentFormat) {
   if (delta == null) return null;
   const rawPositive = delta >= 0;
   const tri = rawPositive ? "\u25B2" : "\u25BC";
-  let text = `${tri} ${formatValue(delta, cmp.format ?? ".0%")}`;
+  let text2 = `${tri} ${formatValue(delta, cmp.format ?? ".0%")}`;
   if (cmp.amount !== void 0) {
     const amount = resolveValueRef(cmp.amount, data);
-    if (amount != null) text += ` : ${formatValue(amount, cmp.amountFormat ?? parentFormat ?? ",.0f")}`;
+    if (amount != null) text2 += ` : ${formatValue(amount, cmp.amountFormat ?? parentFormat ?? ",.0f")}`;
   }
-  return { label: cmp.label, text, positive: cmp.invert ? !rawPositive : rawPositive };
+  return { label: cmp.label, text: text2, positive: cmp.invert ? !rawPositive : rawPositive };
 }
 function layoutKpi(rect, tokens, framed, f) {
   const font = tokens.font;
@@ -9388,7 +10792,7 @@ function layoutKpi(rect, tokens, framed, f) {
   const contentWidth = Math.max(1, rect.width - pad3 * 2);
   const availTop = rect.y + pad3;
   const availH = Math.max(0, rect.height - pad3 * 2);
-  const labelSize = Math.round(clamp5(f.valueSize * 0.4, font.size.small, font.size.title));
+  const labelSize = Math.round(clamp6(f.valueSize * 0.4, font.size.small, font.size.title));
   const labelH = f.hasLabel ? Math.round(labelSize * 1.35) : 0;
   const valueH = Math.round(f.valueSize * 1.06);
   const deltaSize = font.size.large;
@@ -9481,7 +10885,7 @@ function sparkMarkers(values, xAt, yAt, r, tokens) {
 }
 function sparkScales(values, width, height, markers) {
   const n = values.length;
-  const r = clamp5(Math.min(height, 40) * 0.12, 2.5, 4);
+  const r = clamp6(Math.min(height, 40) * 0.12, 2.5, 4);
   const padX = markers ? r + 1 : 1.75;
   const padY = markers ? r + 1 : 1.75;
   const innerW = Math.max(1, width - padX * 2);
@@ -9926,9 +11330,33 @@ function drawKpiCanvas(surface, kpi, tokens, p) {
     });
   }
 }
-
-// src/charts/sankey.ts
-var center = (n) => (n.y0 + n.y1) / 2;
+
+// src/charts/sankey.ts
+var center = (n) => (n.y0 + n.y1) / 2;
+function clamp7(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function spreadCenters2(ideal, minGap, top, bottom) {
+  const ordered = ideal.map((y, i) => ({ i, y })).sort((a, b) => a.y - b.y);
+  for (let i = 1; i < ordered.length; i += 1) {
+    if (ordered[i].y < ordered[i - 1].y + minGap) ordered[i].y = ordered[i - 1].y + minGap;
+  }
+  const last = ordered[ordered.length - 1];
+  if (last && last.y > bottom) {
+    const shift = last.y - bottom;
+    for (const item of ordered) item.y -= shift;
+  }
+  if (ordered.length && ordered[0].y < top) {
+    let prev = top - minGap;
+    for (const item of ordered) {
+      item.y = Math.max(item.y, prev + minGap);
+      prev = item.y;
+    }
+  }
+  const out = new Array(ideal.length);
+  for (const item of ordered) out[item.i] = item.y;
+  return out;
+}
 function buildGraph(spec, palette) {
   const readS = accessor(spec.encoding.source.field);
   const readT = accessor(spec.encoding.target.field);
@@ -10183,10 +11611,10 @@ function drawSankey(surface, spec, tokens, size) {
     return Math.max(nameW, valW);
   };
   const colExtent = (col) => col.reduce((m, n) => Math.max(m, labelExtent(n)), 0);
-  const LABEL_GAP = 6;
+  const LABEL_GAP2 = 6;
   const capGutter = content.width * 0.3;
-  const leftGutter = Math.min(colExtent(graph.columns[0] ?? []) + LABEL_GAP + 4, capGutter);
-  const rightGutter = graph.maxLayer > 0 ? Math.min(colExtent(graph.columns[graph.maxLayer] ?? []) + LABEL_GAP + 4, capGutter) : 0;
+  const leftGutter = Math.min(colExtent(graph.columns[0] ?? []) + LABEL_GAP2 + 4, capGutter);
+  const rightGutter = graph.maxLayer > 0 ? Math.min(colExtent(graph.columns[graph.maxLayer] ?? []) + LABEL_GAP2 + 4, capGutter) : 0;
   const nodeWidth = sankey.nodeWidth ?? 16;
   const pad3 = sankey.nodePadding ?? 14;
   const area2 = {
@@ -10217,30 +11645,112 @@ function drawSankey(surface, spec, tokens, size) {
   }
   ctx.restore();
   const mid = area2.x + area2.width / 2;
-  for (const n of graph.nodes) {
+  const labelRows = graph.nodes.map((n) => {
     const outerLeft = n.layer === 0;
     const outerRight = n.layer === graph.maxLayer && graph.maxLayer > 0;
     const labelRight = outerRight ? true : outerLeft ? false : n.x0 < mid;
-    const cy = center(n);
-    const left = labelRight ? n.x1 + LABEL_GAP : n.x0 - LABEL_GAP;
-    const transform2 = labelRight ? "translateY(-50%)" : "translate(-100%,-50%)";
-    addOverlayText(surface, tokens, {
+    let left = labelRight ? n.x1 + LABEL_GAP2 : n.x0 - LABEL_GAP2;
+    const nextCol = graph.columns[n.layer + 1] ?? [];
+    const prevCol = graph.columns[n.layer - 1] ?? [];
+    const rightLimit = outerRight || nextCol.length === 0 ? content.x + content.width : Math.min(...nextCol.map((node) => node.x0)) - LABEL_GAP2;
+    const leftLimit = outerLeft || prevCol.length === 0 ? content.x : Math.max(...prevCol.map((node) => node.x1)) + LABEL_GAP2;
+    let maxWidth = labelRight ? rightLimit - left : left - leftLimit;
+    maxWidth = Math.max(0, Math.min(content.width * 0.32, maxWidth));
+    if (labelRight) {
+      left = clamp7(left, content.x, content.x + content.width - 1);
+    } else {
+      left = clamp7(left, content.x + 1, content.x + content.width);
+    }
+    return {
+      node: n,
+      key: `${n.layer}:${labelRight ? "r" : "l"}`,
+      labelRight,
+      cy: center(n),
       left,
+      maxWidth
+    };
+  });
+  const rowGap = 2;
+  const rowHeight = showValues ? f.size.small * 1.2 + rowGap + f.size.tiny * 1.2 : f.size.small * 1.2;
+  const keep = /* @__PURE__ */ new Set();
+  const adjustedY = /* @__PURE__ */ new Map();
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of labelRows) groups.set(row.key, [...groups.get(row.key) ?? [], row]);
+  for (const rows of groups.values()) {
+    const capacity = Math.max(1, Math.floor(content.height / rowHeight));
+    const selected = rows.length <= capacity ? rows : [...rows].sort((a, b) => b.node.value - a.node.value || a.node.index - b.node.index).slice(0, capacity).sort((a, b) => a.cy - b.cy);
+    const centers = spreadCenters2(
+      selected.map((row) => row.cy),
+      rowHeight,
+      content.y + rowHeight / 2,
+      content.y + content.height - rowHeight / 2
+    );
+    selected.forEach((row, i) => {
+      keep.add(row.node);
+      adjustedY.set(row.node, centers[i]);
+    });
+  }
+  const drawableRows = labelRows.filter(
+    (row) => keep.has(row.node) && row.maxWidth >= 8 && measureText(row.node.name, labelFont).width <= row.maxWidth && (!showValues || measureText(formatValue(row.node.value, sankey.encoding.value.format), valueFont).width <= row.maxWidth)
+  );
+  const accepted = [];
+  const occupied = [];
+  const labelBoxFor = (row, text2, font, sizePx, top) => {
+    const width = Math.min(measureText(text2, font).width, row.maxWidth);
+    return {
+      x: row.labelRight ? row.left : row.left - width,
+      y: top - sizePx * 1.2 / 2,
+      width,
+      height: sizePx * 1.2
+    };
+  };
+  for (const row of [...drawableRows].sort((a, b) => {
+    const aOuter = a.node.layer === 0 || a.node.layer === graph.maxLayer ? 1 : 0;
+    const bOuter = b.node.layer === 0 || b.node.layer === graph.maxLayer ? 1 : 0;
+    return bOuter - aOuter || b.node.value - a.node.value || a.node.index - b.node.index;
+  })) {
+    const cy = adjustedY.get(row.node) ?? row.cy;
+    const boxes = [
+      labelBoxFor(row, row.node.name, labelFont, f.size.small, showValues ? cy - f.size.small * 0.62 : cy)
+    ];
+    if (showValues) {
+      boxes.push(
+        labelBoxFor(
+          row,
+          formatValue(row.node.value, sankey.encoding.value.format),
+          valueFont,
+          f.size.tiny,
+          cy + f.size.small * 0.62
+        )
+      );
+    }
+    if (boxes.some((box) => occupied.some((other) => boxesOverlap(box, other, 1)))) continue;
+    occupied.push(...boxes);
+    accepted.push(row);
+  }
+  for (const row of accepted.sort((a, b) => a.node.index - b.node.index)) {
+    const n = row.node;
+    const cy = adjustedY.get(n) ?? row.cy;
+    const transform2 = row.labelRight ? "translateY(-50%)" : "translate(-100%,-50%)";
+    addOverlayText(surface, tokens, {
+      left: row.left,
       top: showValues ? cy - f.size.small * 0.62 : cy,
       text: n.name,
       color: tokens.color.text,
       size: f.size.small,
       weight: f.weight.medium,
-      transform: transform2
+      transform: transform2,
+      maxWidth: row.maxWidth
     });
     if (showValues) {
       addOverlayText(surface, tokens, {
-        left,
+        left: row.left,
         top: cy + f.size.small * 0.62,
         text: formatValue(n.value, sankey.encoding.value.format),
         color: tokens.color.textMuted,
         size: f.size.tiny,
-        transform: transform2
+        transform: transform2,
+        maxWidth: row.maxWidth
       });
     }
   }
@@ -10285,7 +11795,12 @@ function drawSankey(surface, spec, tokens, size) {
 }
 
 // src/charts/choropleth.ts
-var clamp6 = (v, lo, hi) => v < lo ? lo : v > hi ? hi : v;
+var clamp8 = (v, lo, hi) => v < lo ? lo : v > hi ? hi : v;
+function readableWithin4(text2, maxWidth, font) {
+  if (maxWidth <= 0) return false;
+  if (measureText(text2, font).width <= maxWidth) return true;
+  return ellipsize(text2, maxWidth, font).length / Math.max(1, text2.length) >= 0.5;
+}
 function centralMeridian(features) {
   const lons = [];
   for (const feature of features) {
@@ -10326,7 +11841,7 @@ function projector(kind, lon0) {
     return ([lon, lat]) => [wrapLon(lon), lat];
   }
   return ([lon, lat]) => {
-    const phi = clamp6(lat, -85.0511, 85.0511) * Math.PI / 180;
+    const phi = clamp8(lat, -85.0511, 85.0511) * Math.PI / 180;
     return [wrapLon(lon), Math.log(Math.tan(Math.PI / 4 + phi / 2)) * 180 / Math.PI];
   };
 }
@@ -10371,7 +11886,7 @@ function drawLegend3(surface, tokens, legend, domain, scheme, format) {
   if (legend.width <= 0 || legend.height <= 0) return;
   const ctx = surface.marks.ctx;
   const interp = sequential(scheme);
-  const barWidth = Math.floor(clamp6(legend.width * 0.5, 120, 240));
+  const barWidth = Math.floor(clamp8(legend.width * 0.5, 120, 240));
   const barHeight = 10;
   const barX = Math.round(legend.x + (legend.width - barWidth) / 2);
   const barY = Math.round(legend.y + 4);
@@ -10385,21 +11900,33 @@ function drawLegend3(surface, tokens, legend, domain, scheme, format) {
   ctx.lineWidth = 1;
   ctx.strokeRect(barX + 0.5, barY + 0.5, Math.max(0, barWidth - 1), Math.max(0, barHeight - 1));
   const labelTop = barY + barHeight + 3;
-  addOverlayText(surface, tokens, {
-    left: barX,
-    top: labelTop,
-    text: formatValue(domain[0], format),
-    color: tokens.color.textMuted,
-    size: tokens.font.size.small
-  });
-  addOverlayText(surface, tokens, {
-    left: barX + barWidth,
-    top: labelTop,
-    text: formatValue(domain[1], format),
-    color: tokens.color.textMuted,
-    size: tokens.font.size.small,
-    transform: "translateX(-100%)"
-  });
+  const labelBudget = Math.max(0, barWidth / 2 - 4);
+  const labelFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
+  const minLabel = formatValue(domain[0], format);
+  const maxLabel = formatValue(domain[1], format);
+  if (readableWithin4(minLabel, labelBudget, labelFont)) {
+    addOverlayText(surface, tokens, {
+      left: barX,
+      top: labelTop,
+      text: minLabel,
+      color: tokens.color.textMuted,
+      size: tokens.font.size.small,
+      maxWidth: labelBudget,
+      role: "legend"
+    });
+  }
+  if (readableWithin4(maxLabel, labelBudget, labelFont)) {
+    addOverlayText(surface, tokens, {
+      left: barX + barWidth,
+      top: labelTop,
+      text: maxLabel,
+      color: tokens.color.textMuted,
+      size: tokens.font.size.small,
+      transform: "translateX(-100%)",
+      maxWidth: labelBudget,
+      role: "legend"
+    });
+  }
 }
 function drawChoropleth(surface, spec, tokens, size, context) {
   const choropleth = spec;
@@ -11080,9 +12607,9 @@ function applyConditionalFormatting(td, opts, column, colIndex, cell, rowBg, row
   const baseline = diverging2 ? normalized(0, domain) : 0;
   const left = diverging2 ? Math.min(baseline, normalized(numeric, domain)) : 0;
   const width = diverging2 ? Math.abs(normalized(numeric, domain) - baseline) : ratio;
-  const text = document.createElement("span");
-  text.textContent = cf.showValue === false ? "" : formatDisplayValue(cell.value, column);
-  setStyles(text, overlayTextStyles(opts.tokens.color.text));
+  const text2 = document.createElement("span");
+  text2.textContent = cf.showValue === false ? "" : formatDisplayValue(cell.value, column);
+  setStyles(text2, overlayTextStyles(opts.tokens.color.text));
   td.style.background = rowBg;
   if (opts.sketch) {
     const colWidth = opts.widths?.[colIndex] ?? column.width ?? defaultColumnWidth(column);
@@ -11090,8 +12617,8 @@ function applyConditionalFormatting(td, opts, column, colIndex, cell, rowBg, row
     const seed = (opts.sketch.seed ^ Math.imul(rowIndex + 1, 374761393) ^ Math.imul(colIndex + 1, 668265263)) >>> 0;
     const canvas = buildSketchDataBar(opts.sketch, barColor, colWidth, rowHeight, left, width, seed);
     if (canvas) td.appendChild(canvas);
-    td.appendChild(text);
-    applyNegativeStyle(text, cell.value, column);
+    td.appendChild(text2);
+    applyNegativeStyle(text2, cell.value, column);
     return;
   }
   const bar = document.createElement("div");
@@ -11106,8 +12633,8 @@ function applyConditionalFormatting(td, opts, column, colIndex, cell, rowBg, row
     opacity: "0.9",
     pointerEvents: "none"
   });
-  td.append(bar, text);
-  applyNegativeStyle(text, cell.value, column);
+  td.append(bar, text2);
+  applyNegativeStyle(text2, cell.value, column);
 }
 function buildSketchDataBar(sketch, color, colWidth, rowHeight, leftRatio, widthRatio, seed) {
   const avail = Math.max(0, colWidth - 8);
@@ -11246,7 +12773,7 @@ function paintBodyRowCanvas(opts, widths, rowIndex, y, metrics, pen) {
     paintCellBox(opts.ctx, x, y, width, metrics.rowHeight, bg, opts.tokens.color.border, false, pen);
     if (conditional.bar) paintDataBar(opts, x, y, width, metrics.rowHeight, conditional.bar, pen);
     const indent = opts.cellIndent?.(rowIndex, colIndex) ?? 0;
-    const text = conditional.showValue === false ? "" : formatDisplayValue(cell.value, column);
+    const text2 = conditional.showValue === false ? "" : formatDisplayValue(cell.value, column);
     const color = negativeTextColor(cell.value, column, conditional.color ?? opts.tokens.color.text);
     const weight = conditional.weight ?? (cls === "normal" ? opts.tokens.font.weight.normal : opts.tokens.font.weight.bold);
     paintCellValueWithIcon(opts, {
@@ -11254,7 +12781,7 @@ function paintBodyRowCanvas(opts, widths, rowIndex, y, metrics, pen) {
       y,
       width,
       height: metrics.rowHeight,
-      text,
+      text: text2,
       align: column.align,
       color,
       weight,
@@ -11340,8 +12867,8 @@ function paintCellValueWithIcon(opts, input) {
   const iconFont = fontString(opts.tokens.font.size.small, opts.tokens.font.family, opts.tokens.font.weight.bold);
   const iconW = input.icon ? measureText(input.icon, iconFont).width : 0;
   const textMax = Math.max(0, input.width - input.paddingX * 2 - iconW - gap);
-  const text = ellipsize(input.text, textMax, font);
-  const textW = measureText(text, font).width;
+  const text2 = ellipsize(input.text, textMax, font);
+  const textW = measureText(text2, font).width;
   const groupW = textW + iconW + gap;
   let start = input.x + input.paddingX;
   if (input.align === "right") start = input.x + input.width - input.paddingX - groupW;
@@ -11361,21 +12888,21 @@ function paintCellValueWithIcon(opts, input) {
       baseline: "middle"
     });
   }
-  paintRawCellText(opts, textX, midY, text, font, input.color, opts.tokens.font.size.small);
+  paintRawCellText(opts, textX, midY, text2, font, input.color, opts.tokens.font.size.small);
 }
 function paintCellText(opts, input) {
   const font = fontString(opts.tokens.font.size.small, opts.tokens.font.family, input.weight);
   const maxWidth = Math.max(0, input.width - input.paddingX * 2);
-  const text = ellipsize(input.text, maxWidth, font);
+  const text2 = ellipsize(input.text, maxWidth, font);
   const x = input.align === "right" ? input.x + input.width - input.paddingX : input.align === "center" ? input.x + input.width / 2 : input.x + input.paddingX;
-  paintRawCellText(opts, x, input.y + input.height / 2, text, font, input.color, opts.tokens.font.size.small, input.align);
+  paintRawCellText(opts, x, input.y + input.height / 2, text2, font, input.color, opts.tokens.font.size.small, input.align);
 }
-function paintRawCellText(opts, x, y, text, font, color, size, align = "left") {
-  if (!text) return;
+function paintRawCellText(opts, x, y, text2, font, color, size, align = "left") {
+  if (!text2) return;
   paintCanvasText(opts.ctx, {
     x,
     y,
-    text,
+    text: text2,
     font,
     color,
     size,
@@ -12255,9 +13782,9 @@ function makeSelectButton(tokens, label) {
     justifyContent: "space-between",
     gap: `${tokens.spacing.sm}px`
   });
-  const text = document.createElement("span");
-  text.textContent = label;
-  Object.assign(text.style, {
+  const text2 = document.createElement("span");
+  text2.textContent = label;
+  Object.assign(text2.style, {
     overflow: "hidden",
     textOverflow: "ellipsis",
     whiteSpace: "nowrap"
@@ -12266,7 +13793,7 @@ function makeSelectButton(tokens, label) {
   caret.textContent = "\u25BE";
   caret.style.color = tokens.color.textMuted;
   caret.style.flex = "0 0 auto";
-  btn.appendChild(text);
+  btn.appendChild(text2);
   btn.appendChild(caret);
   return btn;
 }
@@ -12321,13 +13848,13 @@ function makeOptionRow(tokens, opts) {
     if (opts.selected) row.style.background = withAlpha2(c.accent, 0.14);
     row.addEventListener("click", () => opts.onToggle());
   }
-  const text = document.createElement("span");
-  text.textContent = opts.label;
-  Object.assign(text.style, {
+  const text2 = document.createElement("span");
+  text2.textContent = opts.label;
+  Object.assign(text2.style, {
     overflow: "hidden",
     textOverflow: "ellipsis"
   });
-  row.appendChild(text);
+  row.appendChild(text2);
   return row;
 }
 function makeChip(tokens, label, active = false) {
@@ -12353,8 +13880,8 @@ function makeDualSlider(tokens, opts) {
   const span = Math.max(1e-9, opts.max - opts.min);
   const step = opts.step && opts.step > 0 ? opts.step : span / 100;
   const fmt = opts.format ?? ((v) => String(Math.round(v)));
-  let low = clamp7(opts.low, opts.min, opts.max);
-  let high = clamp7(opts.high, low, opts.max);
+  let low = clamp9(opts.low, opts.min, opts.max);
+  let high = clamp9(opts.high, low, opts.max);
   const wrap = document.createElement("div");
   Object.assign(wrap.style, {
     position: "relative",
@@ -12448,7 +13975,7 @@ function makeDualSlider(tokens, opts) {
   paint();
   const quantize = (v) => {
     const snapped = Math.round((v - opts.min) / step) * step + opts.min;
-    return clamp7(snapped, opts.min, opts.max);
+    return clamp9(snapped, opts.min, opts.max);
   };
   const dragThumb = (which, startEvent) => {
     startEvent.preventDefault();
@@ -12456,8 +13983,8 @@ function makeDualSlider(tokens, opts) {
     const move = (e) => {
       const ratio = rect.width <= 0 ? 0 : (e.clientX - rect.left) / rect.width;
       const v = quantize(opts.min + ratio * span);
-      if (which === "low") low = clamp7(v, opts.min, high);
-      else high = clamp7(v, low, opts.max);
+      if (which === "low") low = clamp9(v, opts.min, high);
+      else high = clamp9(v, low, opts.max);
       paint();
       opts.onInput?.(low, high);
     };
@@ -12475,8 +14002,8 @@ function makeDualSlider(tokens, opts) {
     const dir = e.key === "ArrowRight" || e.key === "ArrowUp" ? 1 : e.key === "ArrowLeft" || e.key === "ArrowDown" ? -1 : 0;
     if (dir === 0) return;
     e.preventDefault();
-    if (which === "low") low = clamp7(quantize(low + dir * step), opts.min, high);
-    else high = clamp7(quantize(high + dir * step), low, opts.max);
+    if (which === "low") low = clamp9(quantize(low + dir * step), opts.min, high);
+    else high = clamp9(quantize(high + dir * step), low, opts.max);
     paint();
     opts.onInput?.(low, high);
     opts.onChange(low, high);
@@ -12486,8 +14013,8 @@ function makeDualSlider(tokens, opts) {
   return {
     el: wrap,
     set(nextLow, nextHigh) {
-      low = clamp7(nextLow, opts.min, opts.max);
-      high = clamp7(nextHigh, low, opts.max);
+      low = clamp9(nextLow, opts.min, opts.max);
+      high = clamp9(nextHigh, low, opts.max);
       paint();
     }
   };
@@ -12513,11 +14040,11 @@ function positionPopover(pop, anchor) {
     pop.style.maxHeight = `${Math.max(80, spaceAbove - gap)}px`;
   }
 }
-function clamp7(v, lo, hi) {
+function clamp9(v, lo, hi) {
   return v < lo ? lo : v > hi ? hi : v;
 }
 function thumbLeftCss(pct) {
-  const fraction = clamp7(pct, 0, 100) / 100;
+  const fraction = clamp9(pct, 0, 100) / 100;
   return `calc(8px + ${fraction} * (100% - 16px))`;
 }
 function withAlpha2(color, alpha) {
@@ -12781,7 +14308,7 @@ function drawSearchCanvas(surface, s, tokens, size, context) {
   const rect = drawTitleBlock(surface, tokens, size, s.title ?? slicerLabel(s));
   const current = currentValue(s, context);
   const value = current?.kind === "text" ? current.query : "";
-  const text = value || (s.placeholder ?? `Search ${s.field}\u2026`);
+  const text2 = value || (s.placeholder ?? `Search ${s.field}\u2026`);
   const h = Math.min(42, Math.max(32, rect.height));
   const y = rect.y + Math.max(0, (rect.height - h) * 0.12);
   ctx.save();
@@ -12801,7 +14328,7 @@ function drawSearchCanvas(surface, s, tokens, size, context) {
   paintCanvasText(ctx, {
     x: rect.x + tokens.spacing.sm,
     y: y + h / 2,
-    text,
+    text: text2,
     font,
     color: value ? tokens.color.text : tokens.color.textMuted,
     size: tokens.font.size.base,
@@ -13908,71 +15435,67 @@ function drawRightAxisLabels(surface, model) {
   const f = tokens.font;
   const smallFont = fontString(f.size.small, f.family, f.weight.normal);
   const labelLeft = plot.x + plot.width + TICK_SIZE + 4;
-  if (surface.headless) {
-    const ctx = surface.marks.ctx;
-    for (const t of model.right.ticks) {
-      paintCanvasText(ctx, {
-        x: labelLeft,
-        y: t.pos,
-        text: t.label,
-        font: smallFont,
-        color: tokens.color.textMuted,
-        size: f.size.small,
-        baseline: "middle"
-      });
-    }
-    if (model.right.title) {
-      const titleFont = fontString(f.size.base, f.family, f.weight.medium);
-      paintCanvasText(
-        ctx,
-        overlayTextToCanvasCmd(
-          {
-            left: frame.width - Math.round(f.size.base * 0.4),
-            top: plot.y + plot.height / 2,
-            text: model.right.title,
-            color: tokens.color.text,
-            size: f.size.base,
-            transform: "translate(-50%, -50%) rotate(90deg)"
-          },
-          titleFont
-        )
-      );
-    }
-    return;
-  }
-  const overlay = surface.overlay;
-  for (const t of model.right.ticks) {
-    const el = document.createElement("div");
-    el.textContent = t.label;
-    el.style.position = "absolute";
-    el.style.left = `${labelLeft}px`;
-    el.style.top = `${t.pos}px`;
-    el.style.font = smallFont;
-    el.style.fontSize = `${f.size.small}px`;
-    el.style.color = tokens.color.textMuted;
-    el.style.whiteSpace = "nowrap";
-    el.style.transform = "translateY(-50%)";
-    el.style.pointerEvents = "none";
-    overlay.appendChild(el);
+  const labelBudget = Math.max(0, frame.originX + frame.width - labelLeft - 2);
+  const readable = (text2, maxWidth) => maxWidth > 0 && (measureText(text2, smallFont).width <= maxWidth || ellipsize(text2, maxWidth, smallFont).length / Math.max(1, text2.length) >= 0.5);
+  const ticks2 = model.right.ticks.filter((t) => readable(t.label, labelBudget));
+  const minGap = f.size.small * 1.35;
+  const keptTicks = [];
+  for (const t of ticks2) {
+    if (keptTicks.every((k) => Math.abs(k.pos - t.pos) >= minGap)) keptTicks.push(t);
+  }
+  for (const t of keptTicks) {
+    addOverlayText(surface, tokens, {
+      left: labelLeft,
+      top: t.pos,
+      text: t.label,
+      color: tokens.color.textMuted,
+      size: f.size.small,
+      transform: "translateY(-50%)",
+      maxWidth: labelBudget,
+      role: "axis-label"
+    });
   }
   if (model.right.title) {
-    const el = document.createElement("div");
-    el.textContent = model.right.title;
-    el.style.position = "absolute";
-    el.style.left = `${frame.width - Math.round(f.size.base * 0.4)}px`;
-    el.style.top = `${plot.y + plot.height / 2}px`;
-    el.style.font = fontString(f.size.base, f.family, f.weight.medium);
-    el.style.fontSize = `${f.size.base}px`;
-    el.style.fontWeight = String(f.weight.medium);
-    el.style.color = tokens.color.text;
-    el.style.whiteSpace = "nowrap";
-    el.style.transform = "translate(-50%, -50%) rotate(90deg)";
-    el.style.pointerEvents = "none";
-    overlay.appendChild(el);
+    addOverlayText(surface, tokens, {
+      left: frame.width - Math.round(f.size.base * 0.4),
+      top: plot.y + plot.height / 2,
+      text: model.right.title,
+      color: tokens.color.text,
+      size: f.size.base,
+      weight: f.weight.medium,
+      transform: "translate(-50%, -50%) rotate(90deg)",
+      maxWidth: plot.height,
+      role: "axis-title"
+    });
   }
 }
+function prepareAxisLabels3(model) {
+  if (model.frame.density === "compact") {
+    model.base.spec.encoding.y.title = void 0;
+    if (model.base.spec.axes?.y) model.base.spec.axes.y.title = void 0;
+    if (model.right) model.right.title = void 0;
+  }
+  if (model.x.kind !== "band" || model.xTicks.length <= 1) return;
+  const { font, spacing } = model.tokens;
+  const smallFont = fontString(font.size.small, font.family, font.weight.normal);
+  const budget = Math.max(0, model.frame.xLabelMaxWidth);
+  const readable = (text2) => budget > 0 && (measureText(text2, smallFont).width <= budget || ellipsize(text2, budget, smallFont).length / Math.max(1, text2.length) >= 0.5);
+  model.xTicks = model.xTicks.filter((t) => readable(t.label));
+  model.base.xTicks = model.xTicks;
+  model.frame.xLabelAngle = 0;
+  const widest = model.xTicks.reduce((m, t) => Math.max(m, measureText(t.label, smallFont).width), 0);
+  const slot = model.plot.width / Math.max(1, model.xTicks.length);
+  const minStep = Math.max(font.size.small * 1.35, widest + spacing.sm);
+  if (slot < minStep) {
+    const stride = Math.ceil(minStep / Math.max(slot, 1e-6));
+    model.xTicks = model.xTicks.filter((_, i) => i % stride === 0);
+    model.base.xTicks = model.xTicks;
+  }
+  for (const lm of model.layers) lm.model.xTicks = model.xTicks;
+}
 function drawCombo(surface, spec, tokens, size, context) {
   const model = buildComboModel(spec, tokens, size);
+  prepareAxisLabels3(model);
   const emphasis = context?.emphasis ?? null;
   for (const lm of model.layers) lm.model.emphasis = emphasis;
   drawAxesUnderlay(surface, model.base);
@@ -14293,9 +15816,9 @@ function colorLeaves(leaves, treemap, tokens) {
   const fallback = parseColor(tokens.color.surface) ?? parseColor(tokens.color.palette[0] ?? "#14b8a6") ?? { r: 20, g: 184, b: 166, a: 1 };
   const color = treemap.encoding.color;
   const ordinal = ordinalColorScale({ palette: tokens.color.palette });
-  const numericValues = color ? leaves.map((leaf) => leaf.colorNumber).filter((n) => n !== void 0) : [];
-  const numericColor = Boolean(color && (color.type === "quantitative" || numericValues.length > 0 && numericValues.length === leaves.length));
-  const domain = numericValues.length ? [Math.min(...numericValues), Math.max(...numericValues)] : [0, 1];
+  const numericValues2 = color ? leaves.map((leaf) => leaf.colorNumber).filter((n) => n !== void 0) : [];
+  const numericColor = Boolean(color && (color.type === "quantitative" || numericValues2.length > 0 && numericValues2.length === leaves.length));
+  const domain = numericValues2.length ? [Math.min(...numericValues2), Math.max(...numericValues2)] : [0, 1];
   const continuous = sequentialColorScale({ domain, interpolator: sequential(treemap.scheme ?? "teal") });
   for (const leaf of leaves) {
     let fill = fallback;
@@ -14508,7 +16031,7 @@ function drawTreemap(surface, spec, tokens, size, context) {
 }
 
 // src/charts/gauge.ts
-function clamp8(value, min, max) {
+function clamp10(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 function valueField2(ref) {
@@ -14551,22 +16074,22 @@ function strokePoints(ctx, pen, points, color, width, cap2 = "butt") {
   ctx.stroke();
   ctx.restore();
 }
-function drawCenteredMessage(surface, tokens, rect, text) {
+function drawCenteredMessage(surface, tokens, rect, text2) {
   addOverlayText(surface, tokens, {
     left: rect.x,
     top: rect.y + Math.max(CHROME_PAD.top, rect.height / 2 - tokens.font.size.small / 2),
     width: rect.width,
-    text,
+    text: text2,
     color: tokens.color.textMuted,
     size: tokens.font.size.small,
     align: "center"
   });
 }
-var LEGEND_SWATCH3 = 11;
+var LEGEND_SWATCH4 = 11;
 function measureLegendWidth(entries, font) {
   let maxLabel = 0;
   for (const e of entries) maxLabel = Math.max(maxLabel, measureText(e.label, font).width);
-  return Math.ceil(LEGEND_SWATCH3 + 6 + maxLabel + 4);
+  return Math.ceil(LEGEND_SWATCH4 + 6 + maxLabel + 4);
 }
 function drawGaugeLegend(surface, tokens, area2, entries) {
   if (entries.length === 0) return;
@@ -14580,9 +16103,9 @@ function drawGaugeLegend(surface, tokens, area2, entries) {
     const ctx = surface.marks.ctx;
     for (const e of entries) {
       const midY = y + rowH / 2;
-      paintLegendSwatch(ctx, x, midY, "square", e.color, LEGEND_SWATCH3);
+      paintLegendSwatch(ctx, x, midY, "square", e.color, LEGEND_SWATCH4);
       paintCanvasText(ctx, {
-        x: x + LEGEND_SWATCH3 + 6,
+        x: x + LEGEND_SWATCH4 + 6,
         y: midY,
         text: e.label,
         font,
@@ -14605,8 +16128,8 @@ function drawGaugeLegend(surface, tokens, area2, entries) {
     row.style.pointerEvents = "none";
     const swatch = document.createElement("span");
     swatch.style.flex = "0 0 auto";
-    swatch.style.width = `${LEGEND_SWATCH3}px`;
-    swatch.style.height = `${LEGEND_SWATCH3}px`;
+    swatch.style.width = `${LEGEND_SWATCH4}px`;
+    swatch.style.height = `${LEGEND_SWATCH4}px`;
     swatch.style.borderRadius = "2px";
     swatch.style.background = e.color;
     const label = document.createElement("span");
@@ -14670,14 +16193,14 @@ function drawGauge(surface, spec, tokens, size, context) {
   const dialW = Math.max(40, content.width - legendW);
   const availH = Math.max(0, content.height - captionReserve);
   const provR = Math.max(18, Math.min(dialW / 2, availH));
-  const trackWidth = clamp8(provR * 0.17, 14, 54);
-  const edgeGuard = trackWidth / 2 + clamp8(trackWidth * 0.3, 4, 10) + 1;
+  const trackWidth = clamp10(provR * 0.17, 14, 54);
+  const edgeGuard = trackWidth / 2 + clamp10(trackWidth * 0.3, 4, 10) + 1;
   const radius = Math.max(18, Math.min(provR, dialW / 2 - edgeGuard, availH - edgeGuard));
   const cx = content.x + dialW / 2;
   const blockH = radius + trackWidth / 2 + captionReserve;
   const topMargin = Math.max(0, (content.height - blockH) / 2);
   const cy = content.y + topMargin + radius + trackWidth / 2;
-  const toAngle = (v) => Math.PI - clamp8((v - min) / (max - min), 0, 1) * Math.PI;
+  const toAngle = (v) => Math.PI - clamp10((v - min) / (max - min), 0, 1) * Math.PI;
   const sweepT = context?.sweepProgress ?? 1;
   const from = context?.valueFrom ?? min;
   const displayValue = from + (value - from) * sweepT;
@@ -14688,7 +16211,7 @@ function drawGauge(surface, spec, tokens, size, context) {
     strokePoints(ctx, pen, arcPoints(cx, cy, radius, Math.PI, valueAngle), fill, trackWidth);
   }
   if (compare2 != null) {
-    const innerWidth = clamp8(trackWidth * 0.42, 6, 22);
+    const innerWidth = clamp10(trackWidth * 0.42, 6, 22);
     const innerRadius = Math.max(radius * 0.35, radius - trackWidth / 2 - 2 - innerWidth / 2);
     const compareFrom = context?.compareFrom ?? min;
     const displayCompare = compareFrom + (compare2 - compareFrom) * sweepT;
@@ -14699,7 +16222,7 @@ function drawGauge(surface, spec, tokens, size, context) {
   }
   if (targetMark != null) {
     const a = toAngle(targetMark);
-    const overhang = clamp8(trackWidth * 0.3, 4, 10);
+    const overhang = clamp10(trackWidth * 0.3, 4, 10);
     const outer = pointOnArc(cx, cy, radius + trackWidth / 2 + overhang, a);
     const inner = pointOnArc(cx, cy, radius - trackWidth / 2 - overhang, a);
     strokePoints(ctx, pen, [outer, inner], markColor, 3, "round");
@@ -14707,7 +16230,7 @@ function drawGauge(surface, spec, tokens, size, context) {
   if (legendEntries.length) {
     drawGaugeLegend(surface, tokens, { x: content.x, y: content.y, width: content.width, height: content.height }, legendEntries);
   }
-  const valueSize = clamp8(radius * 0.5, 22, 72);
+  const valueSize = clamp10(radius * 0.5, 22, 72);
   addOverlayText(surface, tokens, {
     left: content.x,
     top: cy - radius * 0.32 - valueSize / 2,
@@ -14750,7 +16273,7 @@ function drawGauge(surface, spec, tokens, size, context) {
 }
 
 // src/charts/bullet.ts
-function clamp9(value, min, max) {
+function clamp11(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 function titleText2(title2) {
@@ -14815,11 +16338,11 @@ function drawBullet(surface, spec, tokens, size, context) {
   }
   const labelFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.bold);
   const valueFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
-  const labelW = clamp9(measureText(caption, labelFont).width + 14, 44, Math.max(72, content.width * 0.4));
+  const labelW = clamp11(measureText(caption, labelFont).width + 14, 44, Math.max(72, content.width * 0.4));
   const axisReserve = Math.max(24, tokens.font.size.tiny * 2);
   const availableTrackW = Math.max(0, content.width - labelW);
   const trackW = Math.max(0, availableTrackW - 4);
-  const trackH = clamp9(content.height * 0.22, 28, 40);
+  const trackH = clamp11(content.height * 0.22, 28, 40);
   const trackX = content.x + labelW + 4;
   const trackY = content.y + Math.max(0, (content.height - axisReserve - trackH) / 2);
   const track = { x: trackX, y: trackY, width: trackW, height: trackH };
@@ -14839,7 +16362,7 @@ function drawBullet(surface, spec, tokens, size, context) {
     b: greyStart.b + (greyEnd.b - greyStart.b) * t,
     a: 1
   });
-  const xOf = (v) => clamp9(bulletValueToX(v, min, max, track), track.x, track.x + track.width);
+  const xOf = (v) => clamp11(bulletValueToX(v, min, max, track), track.x, track.x + track.width);
   addOverlayText(surface, tokens, {
     left: content.x,
     top: track.y + track.height / 2 - tokens.font.size.small / 2,
@@ -14880,7 +16403,7 @@ function drawBullet(surface, spec, tokens, size, context) {
   ctx.restore();
   const valueText = formatValue(value, fmt);
   const valueLabelW = measureText(valueText, valueFont).width + 14;
-  const valueLeft = clamp9(xOf(value) - valueLabelW / 2, content.x, content.x + content.width - valueLabelW);
+  const valueLeft = clamp11(xOf(value) - valueLabelW / 2, content.x, content.x + content.width - valueLabelW);
   addOverlayText(surface, tokens, {
     left: valueLeft,
     top: Math.max(content.y, barY - tokens.font.size.small - 6),
@@ -14896,7 +16419,7 @@ function drawBullet(surface, spec, tokens, size, context) {
     const tx = xOf(tick);
     drawLine2(ctx, tx, track.y + track.height, tx, track.y + track.height + 4, tokens.color.textMuted, 1);
     addOverlayText(surface, tokens, {
-      left: clamp9(tx - tickW / 2, track.x, track.x + track.width - tickW),
+      left: clamp11(tx - tickW / 2, track.x, track.x + track.width - tickW),
       top: track.y + track.height + 6,
       text: tickText,
       color: tokens.color.textMuted,
@@ -15286,7 +16809,10 @@ function buildWaterfallModel(spec, tokens, opts) {
   const yLabels = yTickValues.map((v) => fmt ? formatValue(v, fmt) : formatNumber2(v, ","));
   const categories = bars.map((b) => b.label);
   const padding = { ...NO_PADDING, ...spec.padding };
-  const xShow = spec.axes?.x?.show !== false;
+  const xFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
+  const widestXLabel = categories.length ? Math.max(...categories.map((c) => measureText(c, xFont).width)) : 0;
+  const readableXLabels = categories.length <= Math.max(2, Math.floor(opts.width / 52)) && widestXLabel <= opts.width * 0.35;
+  const xShow = spec.axes?.x?.show !== false && readableXLabels;
   const yShow = spec.axes?.y?.show !== false;
   const xTitle = spec.axes?.x?.title ?? spec.encoding.stage.title;
   const yTitle = spec.axes?.y?.title ?? spec.encoding.value.title;
@@ -15331,7 +16857,10 @@ function buildWaterfallModel(spec, tokens, opts) {
       y: yPixel(a.cumulative)
     });
   }
-  const baseAxes = { ...spec.axes, x: { grid: false, ...spec.axes?.x } };
+  const baseAxes = {
+    ...spec.axes,
+    x: { ...spec.axes?.x, grid: false, show: xShow, labels: xShow ? spec.axes?.x?.labels : false }
+  };
   const baseSpec = {
     type: "bar",
     data,
@@ -15458,23 +16987,42 @@ function barLabelText(bar, format) {
   const body = format ? formatValue(bar.delta, format) : formatNumber2(bar.delta, ",");
   return bar.delta > 0 ? `+${body}` : body;
 }
+function clamp12(value, min, max) {
+  if (max < min) return min;
+  return Math.max(min, Math.min(max, value));
+}
+function boxesOverlap2(a, b) {
+  return a.x + a.width > b.x + 2 && b.x + b.width > a.x + 2 && a.y + a.height > b.y + 2 && b.y + b.height > a.y + 2;
+}
 function drawLabels(surface, model) {
   if (!model.showLabels) return;
   const { tokens, plot } = model;
   const size = tokens.font.size.tiny;
+  const lineH = size * 1.2;
+  const font = fontString(size, tokens.font.family, tokens.font.weight.medium);
+  const placed = [];
   for (const bar of model.bars) {
     if (bar.rect.width <= 0 || bar.rect.height <= 0) continue;
-    const text = barLabelText(bar, model.format);
-    const top = Math.max(plot.y - 1, bar.rect.y - size - 3);
+    const text2 = barLabelText(bar, model.format);
+    const textW = measureText(text2, font).width;
+    const budget = Math.min(Math.max(0, bar.rect.width + 12), Math.max(0, surface.width - 2));
+    if (budget < 12 || textW > budget && budget < textW * 0.5) continue;
+    const left = clamp12(bar.rect.x + bar.rect.width / 2 - budget / 2, 1, surface.width - budget - 1);
+    const above = bar.rect.y - lineH - 3;
+    const top = above >= plot.y ? above : clamp12(bar.rect.y + 2, plot.y, plot.y + plot.height - lineH);
+    const box = { x: left, y: top, width: Math.min(textW, budget), height: lineH };
+    if (placed.some((p) => boxesOverlap2(p, box))) continue;
+    placed.push(box);
     addOverlayText(surface, tokens, {
-      left: bar.rect.x - 6,
+      left,
       top,
-      width: bar.rect.width + 12,
-      text,
+      width: budget,
+      text: text2,
       color: tokens.color.text,
       size,
       weight: tokens.font.weight.medium,
-      align: "center"
+      align: "center",
+      maxWidth: budget
     });
   }
 }
@@ -15593,13 +17141,18 @@ function buildSlopeModel(spec, tokens, opts) {
       );
       rightLabelW = Math.max(rightLabelW, measureText(fmtTick2(lastV, fmt), normTiny).width);
     }
-    leftLabelW = Math.ceil(leftLabelW);
-    rightLabelW = Math.ceil(rightLabelW);
+    const maxLeft = Math.max(18, Math.floor(opts.width * 0.28));
+    const maxRight = Math.max(18, Math.floor(opts.width * 0.18));
+    leftLabelW = Math.max(18, Math.min(maxLeft, Math.ceil(leftLabelW)));
+    rightLabelW = Math.max(18, Math.min(maxRight, Math.ceil(rightLabelW)));
   }
-  const labelBand = tokens.font.size.tiny + 4;
+  const labelBand = tokens.font.size.tiny * 2.4 + 8;
   const basePadding = showLabels ? { top: labelBand, right: rightLabelW + 8, bottom: labelBand, left: leftLabelW + 8 } : { top: 0, right: 0, bottom: 0, left: 0 };
   const padding = { ...basePadding, ...spec.padding };
-  const xShow = spec.axes?.x?.show !== false;
+  const xFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
+  const widestXLabel = categories.length ? Math.max(...categories.map((c) => measureText(c, xFont).width)) : 0;
+  const readableXLabels = categories.length <= Math.max(2, Math.floor(opts.width / 52)) && widestXLabel <= opts.width * 0.35;
+  const xShow = spec.axes?.x?.show !== false && readableXLabels;
   const yShow = spec.axes?.y?.show === true;
   const xTitle = spec.axes?.x?.title ?? spec.encoding.x.title;
   const yTitle = spec.axes?.y?.title ?? spec.encoding.y.title;
@@ -15609,7 +17162,7 @@ function buildSlopeModel(spec, tokens, opts) {
     padding,
     font: tokens.font,
     title: titleInput2(spec),
-    xAxis: { show: xShow, labels: categories, title: xTitle, edgeAnchored: false },
+    xAxis: { show: xShow, labels: categories, title: xTitle, edgeAnchored: categories.length <= 2 },
     yAxis: { show: yShow, labels: yLabels, title: yTitle }
   });
   const plot = frame.plot;
@@ -15632,7 +17185,11 @@ function buildSlopeModel(spec, tokens, opts) {
     }
     return { key: group.key, label: group.label, value: group.value, color, points };
   });
-  const baseAxes = { ...spec.axes, y: { grid: false, show: false, ...spec.axes?.y } };
+  const baseAxes = {
+    ...spec.axes,
+    x: { ...spec.axes?.x, show: xShow, labels: xShow ? spec.axes?.x?.labels : false },
+    y: { ...spec.axes?.y, grid: false, show: false, labels: false }
+  };
   const baseSpec = {
     type: "line",
     data,
@@ -15693,9 +17250,13 @@ function buildSlopeModel(spec, tokens, opts) {
 
 // src/charts/slope.ts
 var HIT_RADIUS2 = 8;
+var LABEL_GAP = 3;
 function fmtValue(v, format) {
   return format ? formatValue(v, format) : formatNumber2(v, ",");
 }
+function retainsHalf(text2, tokens, size, weight, budget) {
+  return measureText(text2, fontString(size, tokens.font.family, weight)).width <= budget * 2;
+}
 function drawLines(surface, model, alphaOf) {
   const ctx = surface.marks.ctx;
   const pen = model.sketch ? new RoughPen(ctx, model.sketch) : null;
@@ -15739,6 +17300,28 @@ function drawLines(surface, model, alphaOf) {
   }
   ctx.restore();
 }
+function placeBlocks(blocks, minY, maxY) {
+  const sorted = blocks.slice().sort((a, b) => a.desired - b.desired);
+  if (sorted.length === 0 || maxY <= minY) return [];
+  const height = Math.max(...sorted.map((b) => b.height));
+  const capacity = Math.max(1, Math.floor((maxY - minY + LABEL_GAP) / (height + LABEL_GAP)));
+  const candidates = sorted.length <= capacity ? sorted : sorted.filter((_b, i) => {
+    if (capacity === 1) return i === Math.floor((sorted.length - 1) / 2);
+    const pick = Math.round(i * (capacity - 1) / (sorted.length - 1));
+    return Math.round(pick * (sorted.length - 1) / (capacity - 1)) === i;
+  });
+  let cursor = minY;
+  const placed = candidates.map((block) => {
+    const top = Math.max(cursor, Math.min(block.desired - block.height / 2, maxY - block.height));
+    cursor = top + block.height + LABEL_GAP;
+    return { ...block, top };
+  });
+  const overflow = placed.length ? placed[placed.length - 1].top + placed[placed.length - 1].height - maxY : 0;
+  if (overflow > 0) {
+    for (const block of placed) block.top = Math.max(minY, block.top - overflow);
+  }
+  return placed;
+}
 function drawEndLabels(surface, model, alphaOf) {
   if (!model.showLabels) return;
   const { tokens } = model;
@@ -15746,46 +17329,75 @@ function drawEndLabels(surface, model, alphaOf) {
   const valueSize = tokens.font.size.tiny;
   const leftW = model.leftLabelW;
   const rightW = model.rightLabelW;
+  const minY = model.plot.y;
+  const maxY = model.plot.y + model.plot.height;
+  const leftLineH = labelSize * 1.2;
+  const valueLineH = valueSize * 1.2;
+  const leftBlocks = [];
+  const rightBlocks = [];
   for (const series of model.series) {
     if (series.points.length === 0) continue;
-    const opacity = alphaOf(series) === 1 ? 1 : 0.5;
     const first = series.points[0];
     const last = series.points[series.points.length - 1];
-    addOverlayText(surface, tokens, {
-      left: first.x - 8 - leftW,
-      top: first.y - labelSize - 2,
-      width: leftW,
-      text: series.label,
-      color: series.color,
-      size: labelSize,
-      weight: tokens.font.weight.bold,
-      align: "right",
-      opacity
-    });
-    addOverlayText(surface, tokens, {
-      left: first.x - 8 - leftW,
-      top: first.y + 1,
-      width: leftW,
-      text: fmtValue(first.value, model.format),
-      color: tokens.color.textMuted,
-      size: valueSize,
-      align: "right",
-      opacity
-    });
-    if (last !== first) {
+    leftBlocks.push({ item: series, desired: first.y, height: leftLineH + valueLineH + 3 });
+    if (last !== first) rightBlocks.push({ item: series, desired: last.y, height: valueLineH });
+  }
+  for (const block of placeBlocks(leftBlocks, minY, maxY)) {
+    const series = block.item;
+    const opacity = alphaOf(series) === 1 ? 1 : 0.5;
+    const first = series.points[0];
+    const left = Math.max(0, first.x - 8 - leftW);
+    const budget = Math.max(0, first.x - 8 - left);
+    if (budget < 12) continue;
+    if (retainsHalf(series.label, tokens, labelSize, tokens.font.weight.bold, budget)) {
       addOverlayText(surface, tokens, {
-        left: last.x + 8,
-        top: last.y - valueSize / 2,
-        width: rightW,
-        text: fmtValue(last.value, model.format),
+        left,
+        top: block.top,
+        width: budget,
+        text: series.label,
         color: series.color,
+        size: labelSize,
+        weight: tokens.font.weight.bold,
+        align: "right",
+        opacity,
+        maxWidth: budget
+      });
+    }
+    const firstValue = fmtValue(first.value, model.format);
+    if (retainsHalf(firstValue, tokens, valueSize, tokens.font.weight.normal, budget)) {
+      addOverlayText(surface, tokens, {
+        left,
+        top: block.top + leftLineH + 3,
+        width: budget,
+        text: firstValue,
+        color: tokens.color.textMuted,
         size: valueSize,
-        weight: tokens.font.weight.medium,
-        align: "left",
-        opacity
+        align: "right",
+        opacity,
+        maxWidth: budget
       });
     }
   }
+  for (const block of placeBlocks(rightBlocks, minY, maxY)) {
+    if (model.series.length > 8) break;
+    const series = block.item;
+    const opacity = alphaOf(series) === 1 ? 1 : 0.5;
+    const last = series.points[series.points.length - 1];
+    const lastValue = fmtValue(last.value, model.format);
+    if (!retainsHalf(lastValue, tokens, valueSize, tokens.font.weight.medium, rightW)) continue;
+    addOverlayText(surface, tokens, {
+      left: last.x + 8,
+      top: block.top,
+      width: rightW,
+      text: lastValue,
+      color: series.color,
+      size: valueSize,
+      weight: tokens.font.weight.medium,
+      align: "left",
+      opacity,
+      maxWidth: rightW
+    });
+  }
 }
 function nearestPoint(model, px, py) {
   let best = null;
@@ -15950,6 +17562,19 @@ function measureMax2(labels, font) {
 function valueLabel(value, format) {
   return format ? formatValue(value, format) : formatNumber2(value, ",");
 }
+function clamp13(value, min, max) {
+  if (max < min) return min;
+  return Math.max(min, Math.min(max, value));
+}
+function limitedLegend(entries, width, tokens) {
+  const maxItems = Math.max(2, Math.floor(width / 90));
+  if (entries.length <= maxItems) return entries;
+  const shown = Math.max(1, maxItems - 1);
+  return [
+    ...entries.slice(0, shown),
+    { label: `+${entries.length - shown} more`, color: tokens.color.textMuted, symbol: "circle" }
+  ];
+}
 function drawConnector(ctx, pen, x1, x2, y, width, tokens) {
   if (pen) {
     pen.polyline(
@@ -16011,7 +17636,7 @@ function drawDumbbell(surface, spec, tokens, size, context) {
   const categoryField = dumbbell.encoding.category.field;
   let content = drawTitleBlock(surface, tokens, size, dumbbell.title);
   const legendEntries = model.groups.map((group) => ({ label: group.label, color: group.color, symbol: "circle" }));
-  content = drawCategoricalLegend(surface, tokens, content, legendEntries, "top");
+  content = drawCategoricalLegend(surface, tokens, content, limitedLegend(legendEntries, content.width, tokens), "top");
   if (model.rows.length === 0 || model.groups.length === 0 || content.width <= 0 || content.height <= 0) {
     addOverlayText(surface, tokens, {
       left: content.x,
@@ -16045,26 +17670,37 @@ function drawDumbbell(surface, spec, tokens, size, context) {
   ctx.save();
   ctx.strokeStyle = tokens.color.grid;
   ctx.lineWidth = 1;
+  let tickRight = -Infinity;
+  const tickFont = fontString(tokens.font.size.tiny, tokens.font.family, tokens.font.weight.normal);
   for (const tick of ticks2) {
     const x = xScale.map(tick);
     ctx.beginPath();
     ctx.moveTo(x, plot.y);
     ctx.lineTo(x, plot.y + plot.height);
     ctx.stroke();
+    const text2 = valueLabel(tick, model.format);
+    const textW = measureText(text2, tickFont).width;
+    const budget = Math.min(86, Math.max(0, plot.x + plot.width - plot.x));
+    const left = clamp13(x - budget / 2, 0, size.width - budget);
+    if (budget < 12 || textW > budget || left < tickRight + 4) continue;
     addOverlayText(surface, tokens, {
-      left: x,
+      left,
       top: plot.y + plot.height + 6,
-      text: valueLabel(tick, model.format),
+      width: budget,
+      text: text2,
       color: tokens.color.textMuted,
       size: tokens.font.size.tiny,
-      transform: "translateX(-50%)"
+      align: "center",
+      maxWidth: budget
     });
+    tickRight = left + Math.min(textW, budget);
   }
   ctx.restore();
   const pixelRows = [];
   const dotR = Math.max(4, Math.min(13, yBand.bandwidth * 0.16));
   const connectorW = Math.max(3, Math.min(9, dotR * 0.7));
   const labelGap = Math.round(dotR + 4);
+  const rowLabelEvery = Math.max(1, Math.ceil((tokens.font.size.small * 1.2 + 2) / Math.max(1, yBand.step)));
   for (const row of model.rows) {
     const bandTop = yBand.map(row.catKey);
     if (bandTop === void 0) continue;
@@ -16085,29 +17721,45 @@ function drawDumbbell(surface, spec, tokens, size, context) {
     drawConnector(ctx, pen, pixelDots[0].x, pixelDots[pixelDots.length - 1].x, cy, connectorW, tokens);
     for (const dot of pixelDots) drawDot(ctx, pen, dot.x, cy, dotR, dot.color, tokens);
     ctx.globalAlpha = 1;
-    addOverlayText(surface, tokens, {
-      left: content.x,
-      top: cy,
-      width: Math.max(0, leftGutter - tokens.spacing.sm),
-      text: row.catLabel,
-      color: tokens.color.text,
-      size: tokens.font.size.small,
-      align: "right",
-      transform: "translateY(-50%)"
-    });
+    const rowIndex = pixelRows.length - 1;
+    if (rowIndex % rowLabelEvery === 0) {
+      const labelWidth = Math.max(0, leftGutter - tokens.spacing.sm);
+      if (labelWidth >= 12 && measureText(row.catLabel, labelFont).width <= labelWidth * 2) {
+        addOverlayText(surface, tokens, {
+          left: content.x,
+          top: cy,
+          width: labelWidth,
+          text: row.catLabel,
+          color: tokens.color.text,
+          size: tokens.font.size.small,
+          align: "right",
+          transform: "translateY(-50%)",
+          maxWidth: labelWidth
+        });
+      }
+    }
     if (dumbbell.labels) {
       for (let i = 0; i < pixelDots.length; i++) {
         const dot = pixelDots[i];
-        const atLeft = i === 0 && pixelDots.length > 1;
+        const text2 = formatDumbbellValue(dot.value, model.format);
+        const valueFont = fontString(tokens.font.size.tiny, tokens.font.family, tokens.font.weight.normal);
+        const textW = measureText(text2, valueFont).width;
+        const preferLeft = i === 0 && pixelDots.length > 1;
+        const leftSpace = Math.max(0, dot.x - labelGap);
+        const rightSpace = Math.max(0, size.width - dot.x - labelGap);
+        const atLeft = preferLeft ? leftSpace >= 14 || leftSpace >= rightSpace : rightSpace < 14 && leftSpace > rightSpace;
+        const budget = Math.min(64, atLeft ? leftSpace : rightSpace);
+        if (budget < 12 || textW > budget && budget < textW * 0.45) continue;
         addOverlayText(surface, tokens, {
           left: atLeft ? dot.x - labelGap : dot.x + labelGap,
           top: cy,
-          width: 54,
-          text: formatDumbbellValue(dot.value, model.format),
+          width: budget,
+          text: text2,
           color: tokens.color.textMuted,
           size: tokens.font.size.tiny,
           align: atLeft ? "right" : "left",
-          transform: atLeft ? "translate(-100%,-50%)" : "translateY(-50%)"
+          transform: atLeft ? "translate(-100%,-50%)" : "translateY(-50%)",
+          maxWidth: budget
         });
       }
     }
@@ -16283,7 +17935,7 @@ function drawAnnotations(surface, model) {
   }
   ctx.restore();
 }
-function labelBox(model, horizontalRule, pos, p) {
+function labelBox2(model, horizontalRule, pos, p) {
   const { plot } = model;
   const inset = 6;
   if (horizontalRule) {
@@ -16325,7 +17977,7 @@ function drawAnnotationLabels(surface, model) {
       const axis = ann.axis === "x" ? "x" : "y";
       const p = anchorPixel(model, ann, axis, kindOf(ann));
       if (p === void 0) continue;
-      box = labelBox(model, drawsHorizontalRule(model, axis), ann.labelPosition ?? "end", p);
+      box = labelBox2(model, drawsHorizontalRule(model, axis), ann.labelPosition ?? "end", p);
     }
     const color = ann.color ?? tokens.color.text;
     const pill = { background: withAlpha4(tokens.color.background, 0.72), radius: 3, padX: 3, padY: 1 };
@@ -16468,8 +18120,8 @@ function drawTrendlineLabels(surface, model) {
     const x1 = model.x.pixel(g.xMax);
     const y1 = model.y.pixel(g.fit.predict(g.xMax));
     if (x1 == null || !Number.isFinite(x1) || !Number.isFinite(y1)) continue;
-    const text = `R\xB2=${g.fit.r2.toFixed(2)}`;
-    const labelW = measureText(text, font).width;
+    const text2 = `R\xB2=${g.fit.r2.toFixed(2)}`;
+    const labelW = measureText(text2, font).width;
     const nearRight = x1 + 6 + labelW > plot.x + plot.width;
     const left = nearRight ? x1 - 6 : x1 + 6;
     const align = nearRight ? "right" : "left";
@@ -16479,12 +18131,12 @@ function drawTrendlineLabels(surface, model) {
     if (surface.headless) {
       paintCanvasText(
         surface.marks.ctx,
-        overlayTextToCanvasCmd({ left, top, text, color, size: f.size.small, align, transform: transform2 }, font)
+        overlayTextToCanvasCmd({ left, top, text: text2, color, size: f.size.small, align, transform: transform2 }, font)
       );
       continue;
     }
     const el = document.createElement("div");
-    el.textContent = text;
+    el.textContent = text2;
     el.style.position = "absolute";
     el.style.font = font;
     el.style.fontSize = `${f.size.small}px`;
@@ -16986,6 +18638,8 @@ var MARK_CONTRAST_MIN = 1.5;
 var TEXT_CONTRAST_MIN = 4.5;
 var MAX_DISTINGUISHABLE_SERIES = 8;
 var DEFAULT_POINT_MARKER_RADIUS = 3.5;
+var MAX_READABLE_CATEGORIES = 30;
+var SEVERE_TRUNCATION = 0.5;
 var SEVERITY_RANK = { error: 0, warning: 1, info: 2 };
 var VALUE_CHART_TYPES = /* @__PURE__ */ new Set(["kpi", "gauge", "bullet"]);
 var CONTINUOUS_COLOR_TYPES = /* @__PURE__ */ new Set([
@@ -17044,9 +18698,13 @@ function buildRenderReport(input) {
     checkDegenerateAxis(model, add);
     checkClippedMarks(model, spec, add);
     checkAnnotationOverflow(model, spec, tokens, add);
-    checkAxisLabelOverlap(model, spec, tokens, add);
+    if (input.labels) checkAxisLabelDensity(model, spec, input.labels, add);
+    else checkAxisLabelOverlap(model, spec, tokens, add);
     checkLegendOverflow(model, spec, add);
+    checkCategoryCount(model, add);
+    checkTruncatedBaseline(model, spec, add);
   }
+  if (input.labels?.length) checkLabels(input.labels, size, add);
   if (bg) {
     const specColor = spec.color;
     const usedColors = seriesColors.length ? seriesColors : specColor ? [specColor] : [];
@@ -17226,6 +18884,23 @@ function overflowSides(left, top, right, bottom, plot, eps) {
   if (bottom > plot.y + plot.height + eps) sides.push("bottom");
   return sides;
 }
+function checkAxisLabelDensity(model, spec, labels, add) {
+  if (model.x.kind !== "band") return;
+  const total = model.xTicks.length;
+  if (total < 2) return;
+  const drawn = labels.filter((l) => l.role === "axis-label" && l.axis === "x").length;
+  if (drawn === 0 || drawn >= total) return;
+  add({
+    code: "axis-label-overlap",
+    severity: "warning",
+    axis: "x",
+    message: `Only ${drawn} of ${total} category labels fit on the x-axis; the rest were dropped so the remaining ones stay readable. Widen the chart, reduce categories, or aggregate the long tail.`,
+    details: { drawn, total },
+    ...xLabelAngleFix(spec) ?? {
+      hint: "Rotate x-axis labels, facet the chart, widen it, or aggregate the long tail."
+    }
+  });
+}
 function checkAxisLabelOverlap(model, spec, tokens, add) {
   const ticks2 = model.xTicks;
   if (ticks2.length < 2) return;
@@ -17273,6 +18948,91 @@ function checkLegendOverflow(model, spec, add) {
 function isRecord(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date);
 }
+var MAX_COLLISION_LABELS = 300;
+var LABEL_OVERLAP_TOLERANCE = 2;
+function checkLabels(labels, size, add) {
+  const truncated = labels.filter((l) => l.truncated);
+  if (truncated.length > 0) {
+    const severe = truncated.filter(
+      (l) => l.text.length / Math.max(1, l.fullText.length) < SEVERE_TRUNCATION
+    );
+    const worst2 = severe[0] ?? truncated[0];
+    add({
+      code: "text-clipped",
+      severity: severe.length > 0 ? "warning" : "info",
+      message: `${truncated.length} label${truncated.length === 1 ? " was" : "s were"} shortened to fit (e.g. "${worst2.fullText}" \u2192 "${worst2.text}")` + (severe.length > 0 ? `; ${severe.length} lost more than half their text and no longer read clearly.` : "."),
+      details: {
+        count: truncated.length,
+        severe: severe.length,
+        roles: [...new Set(truncated.map((l) => l.role))],
+        example: { role: worst2.role, full: worst2.fullText, drawn: worst2.text }
+      },
+      hint: "Widen the chart, shorten the label values, or move the legend to the top/bottom."
+    });
+  }
+  const occluded = labels.filter((l) => {
+    const slack = Math.max(1, l.size * 0.25);
+    return l.box.x < -slack || l.box.y < -slack || l.box.x + l.box.width > size.width + slack || l.box.y + l.box.height > size.height + slack;
+  });
+  if (occluded.length > 0) {
+    add({
+      code: "text-occluded",
+      severity: "warning",
+      message: `${occluded.length} label${occluded.length === 1 ? "" : "s"} extend past the chart's edge and are cut off (e.g. the ${occluded[0].role} "${occluded[0].fullText}").`,
+      details: { count: occluded.length, roles: [...new Set(occluded.map((l) => l.role))] },
+      hint: "Increase the chart size, or reduce the chrome competing for space."
+    });
+  }
+  if (labels.length <= MAX_COLLISION_LABELS) {
+    let collisions = 0;
+    let example = null;
+    for (let i = 0; i < labels.length; i += 1) {
+      for (let j = i + 1; j < labels.length; j += 1) {
+        if (!boxesOverlap(labels[i].box, labels[j].box, LABEL_OVERLAP_TOLERANCE)) continue;
+        collisions += 1;
+        if (!example) example = [labels[i], labels[j]];
+      }
+    }
+    if (example) {
+      add({
+        code: "label-collision",
+        severity: "warning",
+        message: `${collisions} pair${collisions === 1 ? "" : "s"} of labels overlap and are hard to read (e.g. the ${example[0].role} "${example[0].text}" over the ${example[1].role} "${example[1].text}").`,
+        details: { collisions, example: [example[0].text, example[1].text] },
+        hint: "Give the chart more room, show fewer categories, or turn off data labels."
+      });
+    }
+  }
+}
+function checkCategoryCount(model, add) {
+  if (model.x.kind !== "band") return;
+  const categories = model.xTicks.length;
+  if (categories <= MAX_READABLE_CATEGORIES) return;
+  add({
+    code: "too-many-categories",
+    severity: "info",
+    axis: "x",
+    message: `${categories} categories share one axis \u2014 beyond ~${MAX_READABLE_CATEGORIES} the bands get too thin to compare individually.`,
+    details: { categories, max: MAX_READABLE_CATEGORIES },
+    hint: 'Aggregate the long tail into an "Other" bucket, filter to a top-N, or use a treemap.'
+  });
+}
+function checkTruncatedBaseline(model, spec, add) {
+  if (spec.type !== "bar") return;
+  const enc = spec.encoding;
+  const y = isRecord(enc) ? enc.y : void 0;
+  const scale = isRecord(y) ? y.scale : void 0;
+  const domain = isRecord(scale) ? scale.domain : void 0;
+  if (!Array.isArray(domain) || typeof domain[0] !== "number" || domain[0] <= 0) return;
+  add({
+    code: "truncated-baseline",
+    severity: "warning",
+    axis: "y",
+    message: `The bar value axis starts at ${domain[0]} rather than 0, so bar lengths no longer encode magnitude and small differences look large.`,
+    details: { start: domain[0] },
+    fix: [{ op: "remove", path: "/encoding/y/scale/domain" }]
+  });
+}
 function xLabelAngleFix(spec) {
   const axes = spec.axes;
   if (!isRecord(axes)) return void 0;
@@ -17590,14 +19350,14 @@ ${e instanceof Error ? e.message : String(e)}`;
 }
 function buildSummaryPanel(spec, tokens) {
   const { card, body } = makePanel("Summary", tokens);
-  let text = "";
+  let text2 = "";
   try {
-    text = summarize(spec);
+    text2 = summarize(spec);
   } catch {
-    text = "";
+    text2 = "";
   }
-  body.textContent = text || "\u2014 (no summary for this chart type)";
-  if (!text) setStyle(body, { color: tokens.color.textMuted });
+  body.textContent = text2 || "\u2014 (no summary for this chart type)";
+  if (!text2) setStyle(body, { color: tokens.color.textMuted });
   return card;
 }
 function diagnosticRow(path, message, color, tokens) {
@@ -18206,7 +19966,8 @@ function render(target, spec, options) {
       data: filtered,
       tokens,
       size,
-      model: reportModel
+      model: reportModel,
+      labels: surface.labels.records
     });
     if (!entrance) signalReady(surface);
     armFontRefresh();
@@ -18695,7 +20456,7 @@ function stripCellHeight(view, rowHeight) {
   if (view.spec.type === "range") return Math.max(base, 132 + titlePad);
   return Math.max(base, 96 + titlePad);
 }
-var clamp10 = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+var clamp14 = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
 function defaultSpan(spec, cols) {
   const t = spec.type;
   if (isSlicerType(t)) return { w: Math.min(3, cols), h: 2 };
@@ -19165,7 +20926,7 @@ function renderDashboard(target, spec, options) {
           if (resp?.hidden) continue;
           const w = resp?.w ?? c.w;
           const h = resp?.h ?? c.h;
-          const scaledW = clamp10(Math.round(w * effCols / group.baseCols), 1, effCols);
+          const scaledW = clamp14(Math.round(w * effCols / group.baseCols), 1, effCols);
           c.el.style.gridColumn = fullWidth && c.x != null ? `${c.x} / span ${Math.min(w, group.baseCols)}` : `span ${scaledW}`;
           c.el.style.gridRow = fullWidth && c.y != null ? `${c.y} / span ${h}` : `span ${h}`;
         }
@@ -19279,12 +21040,76 @@ function renderDashboard(target, spec, options) {
 // src/runtime/dashboardHeadless.ts
 var HEADER_H = 44;
 var SECTION_TITLE_H = 26;
+var SECTION_SUBTITLE_H = 18;
+var CARD_HEADER_TITLE_H = 22;
+var CARD_HEADER_SUBTITLE_H = 18;
+var ACCENT_W = 5;
+var DEFAULT_BREAKPOINTS2 = [
+  { maxWidth: 600, cols: 1 },
+  { maxWidth: 960, cols: 6 }
+];
+function clamp15(v, lo, hi) {
+  return Math.max(lo, Math.min(hi, v));
+}
+function text(target, ledger, opts) {
+  const font = fontString(opts.size, resolveTheme(void 0).font.family, opts.weight ?? 400);
+  const fitted = fitLabel(opts.text, opts.width, font);
+  const overlay = {
+    left: opts.x,
+    top: opts.y,
+    width: opts.width,
+    text: fitted.text,
+    color: opts.color,
+    size: opts.size,
+    align: opts.align
+  };
+  paintCanvasText(target.marks, {
+    x: opts.x,
+    y: opts.y,
+    text: fitted.text,
+    font,
+    color: opts.color,
+    size: opts.size,
+    align: opts.align,
+    baseline: "top"
+  });
+  const box = labelBox(overlay, font);
+  recordLabel(ledger, {
+    role: opts.role,
+    text: fitted.text,
+    fullText: opts.text,
+    truncated: fitted.truncated,
+    box: box.box,
+    angle: box.angle,
+    size: opts.size,
+    budget: opts.width
+  });
+}
+function childDiagnostic(view, diagnostic) {
+  return {
+    ...diagnostic,
+    message: `View "${view.id}": ${diagnostic.message}`,
+    details: { ...diagnostic.details ?? {}, viewId: view.id, viewType: view.spec.type }
+  };
+}
 function renderDashboardToContext(target, spec) {
   const ctx = target.marks;
   const tokens = resolveTheme(spec.theme);
   const layout2 = resolveDashboardLayout(spec.layout);
   const gap = layout2.gap;
   const pad3 = layout2.padding ?? Math.round(gap * 1.4);
+  const pageW = layout2.maxWidth ? Math.min(target.width, layout2.maxWidth) : target.width;
+  const pageX = Math.max(0, (target.width - pageW) / 2);
+  const innerW = Math.max(1, pageW - pad3 * 2);
+  const ledger = new LabelLedger();
+  const diagnostics = [];
+  const breakpoints = (layout2.breakpoints ?? DEFAULT_BREAKPOINTS2).slice().sort((a, b) => a.maxWidth - b.maxWidth);
+  const effectiveCols = (width, cols) => {
+    for (const bp of breakpoints) {
+      if (width <= bp.maxWidth) return Math.max(1, Math.min(bp.cols, cols));
+    }
+    return cols;
+  };
   ctx.save();
   ctx.fillStyle = spec.background ?? tokens.color.background;
   ctx.fillRect(0, 0, target.width, target.height);
@@ -19294,15 +21119,30 @@ function renderDashboardToContext(target, spec) {
   if (titleText3 || spec.subtitle) {
     ctx.save();
     ctx.fillStyle = tokens.color.accent;
-    ctx.fillRect(pad3, cursorY + 2, 5, 30);
-    ctx.fillStyle = tokens.color.text;
-    ctx.textBaseline = "top";
-    ctx.font = `${tokens.font.weight.bold} ${tokens.font.size.title}px ${tokens.font.family}`;
-    if (titleText3) ctx.fillText(titleText3, pad3 + 14, cursorY + 2);
+    ctx.fillRect(pageX + pad3, cursorY + 2, ACCENT_W, 30);
+    if (titleText3) {
+      text(target, ledger, {
+        text: titleText3,
+        x: pageX + pad3 + 14,
+        y: cursorY + 2,
+        width: Math.max(1, innerW - 14),
+        color: tokens.color.text,
+        size: tokens.font.size.title,
+        weight: tokens.font.weight.bold,
+        role: "title"
+      });
+    }
     if (spec.subtitle) {
-      ctx.fillStyle = tokens.color.textMuted;
-      ctx.font = `${tokens.font.weight.normal} ${tokens.font.size.small}px ${tokens.font.family}`;
-      ctx.fillText(spec.subtitle, pad3 + 14, cursorY + 24);
+      text(target, ledger, {
+        text: spec.subtitle,
+        x: pageX + pad3 + 14,
+        y: cursorY + 24,
+        width: Math.max(1, innerW - 14),
+        color: tokens.color.textMuted,
+        size: tokens.font.size.small,
+        weight: tokens.font.weight.normal,
+        role: "subtitle"
+      });
     }
     ctx.restore();
     cursorY += HEADER_H;
@@ -19315,50 +21155,133 @@ function renderDashboardToContext(target, spec) {
   for (const section of sections) {
     if (section.collapsed) continue;
     if (section.section?.title) {
-      ctx.save();
-      ctx.fillStyle = tokens.color.text;
-      ctx.textBaseline = "top";
-      ctx.font = `${tokens.font.weight.bold} ${tokens.font.size.base}px ${tokens.font.family}`;
-      ctx.fillText(section.section.title, pad3, cursorY);
-      ctx.restore();
+      text(target, ledger, {
+        text: section.section.title,
+        x: pageX + pad3,
+        y: cursorY,
+        width: innerW,
+        color: tokens.color.text,
+        size: tokens.font.size.base,
+        weight: tokens.font.weight.bold,
+        role: "title"
+      });
       cursorY += SECTION_TITLE_H;
     }
-    const cols = Math.max(1, section.cols);
-    const innerW = target.width - pad3 * 2;
+    if (section.section?.subtitle) {
+      text(target, ledger, {
+        text: section.section.subtitle,
+        x: pageX + pad3,
+        y: cursorY - 8,
+        width: innerW,
+        color: tokens.color.textMuted,
+        size: tokens.font.size.small,
+        weight: tokens.font.weight.normal,
+        role: "subtitle"
+      });
+      cursorY += SECTION_SUBTITLE_H;
+    }
+    const baseCols = Math.max(1, section.cols);
+    const cols = effectiveCols(innerW, baseCols);
     const colW = (innerW - gap * (cols - 1)) / cols;
-    const cells = placeViews(section.views, cols, layout2.preset);
+    const cells = placeViews(section.views, baseCols, layout2.preset);
     const flow = { x: 1, y: 1, rowH: 0 };
     let maxBottom = cursorY;
     for (const cell of cells) {
-      let gx = cell.x;
-      let gy = cell.y;
+      const scaledW = clamp15(Math.round(cell.w * cols / baseCols), 1, cols);
+      const fullWidth = cols === baseCols;
+      let gx = fullWidth ? cell.x : void 0;
+      let gy = fullWidth ? cell.y : void 0;
       if (gx == null || gy == null) {
-        if (flow.x + cell.w - 1 > cols) {
+        if (flow.x + scaledW - 1 > cols) {
           flow.x = 1;
           flow.y += Math.max(1, flow.rowH);
           flow.rowH = 0;
         }
         gx = flow.x;
         gy = flow.y;
-        flow.x += cell.w;
+        flow.x += scaledW;
         flow.rowH = Math.max(flow.rowH, cell.h);
       }
-      const cx = pad3 + (gx - 1) * (colW + gap);
+      const cx = pageX + pad3 + (gx - 1) * (colW + gap);
       const cy = cursorY + (gy - 1) * (section.rowHeight + gap);
-      const cw = cell.w * colW + (cell.w - 1) * gap;
+      const cw = scaledW * colW + (scaledW - 1) * gap;
       const ch = cell.h * section.rowHeight + (cell.h - 1) * gap;
-      const viewSpec = inheritInto(cell.view.spec, spec, tokens);
+      const framed = cell.view.frame ?? true;
+      const hasHeader = !!(cell.view.title || cell.view.subtitle);
+      const inset = cell.view.padding === "none" ? 0 : tokens.spacing.sm;
+      const headerH = hasHeader ? tokens.spacing.sm + (cell.view.title ? CARD_HEADER_TITLE_H : 0) + (cell.view.subtitle ? CARD_HEADER_SUBTITLE_H : 0) + tokens.spacing.xs : 0;
+      ctx.save();
+      if (cell.view.background || framed) {
+        ctx.fillStyle = cell.view.background ?? tokens.color.surface;
+        ctx.fillRect(cx, cy, cw, ch);
+      }
+      if (framed) {
+        ctx.strokeStyle = tokens.color.border;
+        ctx.lineWidth = 1;
+        ctx.strokeRect(cx, cy, cw, ch);
+      }
+      if (cell.view.accent) {
+        ctx.fillStyle = cell.view.accent;
+        ctx.fillRect(cx, cy, ACCENT_W, ch);
+      }
+      if (cell.view.title) {
+        text(target, ledger, {
+          text: cell.view.title,
+          x: cx + tokens.spacing.md,
+          y: cy + tokens.spacing.sm,
+          width: Math.max(1, cw - tokens.spacing.md * 2),
+          color: tokens.color.text,
+          size: tokens.font.size.base,
+          weight: tokens.font.weight.medium,
+          role: "title"
+        });
+      }
+      if (cell.view.subtitle) {
+        text(target, ledger, {
+          text: cell.view.subtitle,
+          x: cx + tokens.spacing.md,
+          y: cy + tokens.spacing.sm + (cell.view.title ? CARD_HEADER_TITLE_H : 0),
+          width: Math.max(1, cw - tokens.spacing.md * 2),
+          color: tokens.color.textMuted,
+          size: tokens.font.size.small,
+          weight: tokens.font.weight.normal,
+          role: "subtitle"
+        });
+      }
+      ctx.restore();
+      const contentX = cx + inset;
+      const contentY = cy + headerH + inset;
+      const contentW = cw - inset * 2;
+      const contentH = ch - headerH - inset * 2;
+      const viewSpec = inheritInto(cell.view.spec, spec, tokens, hasHeader);
       ctx.save();
-      ctx.translate(cx, cy);
+      ctx.translate(contentX, contentY);
       ctx.beginPath();
-      ctx.rect(0, 0, cw, ch);
+      ctx.rect(0, 0, contentW, contentH);
       ctx.clip();
       try {
-        const r = renderToContext({ marks: ctx, interaction: target.interaction, width: cw, height: ch }, viewSpec);
-        markCount += r.markCount;
-        if (!r.ok) allOk = false;
+        if (contentW <= 1 || contentH <= 1) {
+          diagnostics.push({
+            code: "empty-view",
+            severity: "error",
+            message: `View "${cell.view.id}" collapsed to ${Math.round(contentW)}\xD7${Math.round(contentH)}px.`,
+            details: { viewId: cell.view.id, viewType: cell.view.spec.type }
+          });
+          allOk = false;
+        } else {
+          const r = renderToContext({ marks: ctx, interaction: target.interaction, width: contentW, height: contentH }, viewSpec);
+          markCount += r.markCount;
+          diagnostics.push(...r.diagnostics.map((d) => childDiagnostic(cell.view, d)));
+          if (!r.ok) allOk = false;
+        }
         views++;
-      } catch {
+      } catch (error) {
+        diagnostics.push({
+          code: "view-render-error",
+          severity: "error",
+          message: `View "${cell.view.id}" failed to render: ${error?.message ?? String(error)}`,
+          details: { viewId: cell.view.id, viewType: cell.view.spec.type }
+        });
         allOk = false;
       }
       ctx.restore();
@@ -19366,14 +21289,27 @@ function renderDashboardToContext(target, spec) {
     }
     cursorY = maxBottom + gap;
   }
+  const chromeReport = buildRenderReport({
+    type: "kpi",
+    spec: { type: "kpi", value: 1, theme: spec.theme, background: spec.background ?? tokens.color.background },
+    data: [{ value: 1 }],
+    tokens,
+    size: { width: target.width, height: target.height },
+    labels: ledger.records
+  });
+  diagnostics.push(...chromeReport.diagnostics.map((d) => ({ ...d, message: `Dashboard chrome: ${d.message}` })));
+  diagnostics.sort((a, b) => {
+    const rank2 = { error: 0, warning: 1, info: 2 };
+    return rank2[a.severity] - rank2[b.severity];
+  });
   return {
     type: "dashboard",
     size: { width: target.width, height: target.height },
     markCount,
     seriesCount: views,
     colorCount: 1,
-    ok: allOk,
-    diagnostics: [],
+    ok: allOk && !diagnostics.some((d) => d.severity === "error" || d.severity === "warning"),
+    diagnostics,
     summary: `Dashboard of ${views} view${views === 1 ? "" : "s"}.`
   };
 }
@@ -19398,7 +21334,8 @@ function renderToContext(target, spec) {
     height: size.height,
     dpr: 1,
     marks: { ctx },
-    interaction: { ctx: target.interaction ?? ctx }
+    interaction: { ctx: target.interaction ?? ctx },
+    labels: new LabelLedger()
   };
   const bg = spec.background ?? tokens.color.background;
   ctx.save();
@@ -19449,12 +21386,73 @@ function renderToContext(target, spec) {
     };
     renderer(surface, effectiveSpec, tokens, size, rctx);
   }
-  return buildRenderReport({ type, spec, data, tokens, size, model: reportModel });
+  return buildRenderReport({
+    type,
+    spec,
+    data,
+    tokens,
+    size,
+    model: reportModel,
+    labels: surface.labels.records
+  });
+}
+
+// src/runtime/draft.ts
+function isDashboard(spec) {
+  return typeof spec === "object" && spec !== null && spec.type === "dashboard";
+}
+function draft(spec, options = {}) {
+  const shouldRepair = options.repair ?? true;
+  const level = options.repairLevel ?? "safe";
+  let working = spec;
+  let patches = [];
+  let repairs = [];
+  let validation = validateSpec(working);
+  if (shouldRepair && (!validation.valid || level === "data")) {
+    const repaired = repairSpec(working, { level });
+    working = repaired.spec;
+    patches = repaired.applied;
+    repairs = repaired.appliedDetails;
+    validation = validateSpec(working);
+  }
+  if (!validation.valid) {
+    return {
+      spec: working,
+      valid: false,
+      rendered: false,
+      patches,
+      repairs,
+      errors: validation.errors,
+      warnings: validation.warnings
+    };
+  }
+  const result = {
+    spec: working,
+    valid: true,
+    rendered: false,
+    patches,
+    repairs,
+    errors: [],
+    warnings: validation.warnings,
+    summary: isDashboard(working) ? void 0 : summarize(working) || void 0
+  };
+  if (options.target) {
+    result.report = renderToContext(options.target, working);
+    result.rendered = true;
+    result.summary = result.report.summary ?? result.summary;
+  } else if (options.container && !isDashboard(working)) {
+    const instance = render(options.container, working, options.renderOptions);
+    result.instance = instance;
+    result.report = instance.report();
+    result.rendered = true;
+    result.summary = result.report.summary ?? result.summary;
+  }
+  return result;
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.18.0";
 
-export { CARTESIAN_TYPES, CHART_TYPES, CanvasLayer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, ExpressionError, FACETABLE_TYPES2 as FACETABLE_TYPES, FUNCTION_NAMES, InteractionController, NO_PADDING, RoughPen, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SPEC_ATTR, SR_ONLY_STYLE, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, TYPE_ATTR, Tooltip, VERSION, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp012 as clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createInspector, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawDebugCanvas, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatCountUp, formatDate, formatNumber2 as formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, relativeLuminance, render, renderDashboard, renderDebugView, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, resolveValueRef, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, serializeSpec, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, stripData, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
+export { CARTESIAN_TYPES, CHART_TYPES, CanvasLayer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, ExpressionError, FACETABLE_TYPES2 as FACETABLE_TYPES, FUNCTION_NAMES, InteractionController, LabelLedger, MIN_VIABLE_PLOT_SIZE, NO_PADDING, RoughPen, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SPEC_ATTR, SR_ONLY_STYLE, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, TYPE_ATTR, Tooltip, VERSION, adaptPaletteForDarkBackground, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, boxesOverlap, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp012 as clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createInspector, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, draft, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawDebugCanvas, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fitLabel, fontString, formatCountUp, formatDate, formatNumber2 as formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, labelBox, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, listChartTypes, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, recordLabel, relativeLuminance, render, renderDashboard, renderDebugView, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveThemeChecked, resolveUpdate, resolveValueRef, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, serializeSpec, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, starterSpec, stripData, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map