@opendata-ai/openchart-engine 6.11.0 → 6.13.0

package/src/charts/post-process.ts

@@ -0,0 +1,215 @@
+/**
+ * Mark post-processing: obstacle computation, renderer dispatch, and
+ * animation index assignment. These are mark-type-aware operations that
+ * run after the chart renderer has produced marks.
+ */
+
+import type {
+  Encoding,
+  Mark,
+  MarkDef,
+  PointMark,
+  Rect,
+  RectMark,
+  ResolvedAnimation,
+} from '@opendata-ai/openchart-core';
+import type { ResolvedScales } from '../layout/scales';
+
+// ---------------------------------------------------------------------------
+// Mark obstacles for annotation collision avoidance
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute bounding rects from marks to use as obstacles for annotation nudging.
+ *
+ * For band-scale charts (bar, dot): groups marks by band row and returns
+ * a single obstacle per row spanning the full band height and x-range.
+ *
+ * For other charts (column, scatter): returns individual mark bounds so
+ * annotations avoid overlapping any visible data mark.
+ */
+export function computeMarkObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
+  // Band-scale y-axis: group marks by row for efficient obstacle computation
+  if (scales.y?.type === 'band') {
+    return computeBandRowObstacles(marks, scales);
+  }
+
+  // All other charts: use individual rect/point mark bounds as obstacles
+  const obstacles: Rect[] = [];
+  for (const mark of marks) {
+    if (mark.type === 'rect') {
+      const rm = mark as RectMark;
+      obstacles.push({ x: rm.x, y: rm.y, width: rm.width, height: rm.height });
+    } else if (mark.type === 'point') {
+      const pm = mark as PointMark;
+      obstacles.push({
+        x: pm.cx - pm.r,
+        y: pm.cy - pm.r,
+        width: pm.r * 2,
+        height: pm.r * 2,
+      });
+    }
+  }
+  return obstacles;
+}
+
+/** Group band-scale marks by row, returning one obstacle per band. */
+function computeBandRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
+  const rows = new Map<number, { minX: number; maxX: number; bandY: number }>();
+
+  for (const mark of marks) {
+    let cy: number;
+    let left: number;
+    let right: number;
+
+    if (mark.type === 'point') {
+      const pm = mark as PointMark;
+      cy = pm.cy;
+      left = pm.cx - pm.r;
+      right = pm.cx + pm.r;
+    } else if (mark.type === 'rect') {
+      const rm = mark as RectMark;
+      cy = rm.y + rm.height / 2;
+      left = rm.x;
+      right = rm.x + rm.width;
+    } else {
+      continue;
+    }
+
+    // Round cy to group marks on the same band
+    const key = Math.round(cy);
+    const existing = rows.get(key);
+    if (existing) {
+      existing.minX = Math.min(existing.minX, left);
+      existing.maxX = Math.max(existing.maxX, right);
+    } else {
+      rows.set(key, { minX: left, maxX: right, bandY: cy });
+    }
+  }
+
+  // Get bandwidth from the band scale
+  const bandScale = scales.y!.scale as { bandwidth?: () => number };
+  const bandwidth = bandScale.bandwidth?.() ?? 0;
+  if (bandwidth === 0) return [];
+
+  const obstacles: Rect[] = [];
+  for (const { minX, maxX, bandY } of rows.values()) {
+    obstacles.push({
+      x: minX,
+      y: bandY - bandwidth / 2,
+      width: maxX - minX,
+      height: bandwidth,
+    });
+  }
+
+  return obstacles;
+}
+
+// ---------------------------------------------------------------------------
+// Renderer key dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the renderer key from mark type, encoding, and mark definition.
+ *
+ * - 'bar' -> 'bar' (horizontal) or 'bar:vertical' based on encoding axis types
+ * - 'arc' -> 'arc' (pie) or 'arc:donut' based on innerRadius
+ * - All other mark types pass through unchanged
+ */
+export function resolveRendererKey(
+  markType: string,
+  encoding: Partial<Encoding>,
+  markDef: Partial<MarkDef>,
+): string {
+  if (markType === 'bar') {
+    const xType = encoding.x?.type;
+    const yType = encoding.y?.type;
+    const isVertical =
+      (xType === 'nominal' || xType === 'ordinal' || xType === 'temporal') &&
+      yType === 'quantitative';
+    if (isVertical) {
+      return 'bar:vertical';
+    }
+  } else if (markType === 'arc') {
+    const innerRadius = markDef.innerRadius;
+    if (innerRadius && innerRadius > 0) {
+      return 'arc:donut';
+    }
+  }
+  return markType;
+}
+
+// ---------------------------------------------------------------------------
+// Animation index assignment
+// ---------------------------------------------------------------------------
+
+/** Extract the primary quantitative value from a mark for value-based stagger ordering. */
+function getMarkPrimaryValue(mark: Mark): number {
+  switch (mark.type) {
+    case 'rect':
+      return mark.height; // bar height is the primary value encoding
+    case 'point':
+      return mark.cy; // y position for scatter
+    case 'arc':
+      return mark.endAngle - mark.startAngle; // arc angle extent
+    case 'line':
+    case 'area':
+      return 0; // series marks don't have individual values
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Assign animation indices to marks for stagger ordering.
+ *
+ * Two phases:
+ * 1. Value-based stagger: sorts marks by primary value, assigns sequential indices.
+ *    Skips stacked rects since they get group-based indices in phase 2.
+ * 2. Stack-based stagger: groups marks by stackGroup, assigns the same index to
+ *    all segments in a group, and computes stackPos (segment position: 0, 1, 2...).
+ *    This intentionally overwrites any value-based indices for stacked marks.
+ */
+export function assignAnimationIndices(
+  marks: Mark[],
+  animation: ResolvedAnimation | undefined,
+): void {
+  if (!animation?.enabled) return;
+
+  // Phase 1: Value-based stagger ordering. Skip stacked rects
+  // since they get group-based indices below (avoids wasted work that gets overwritten).
+  if (animation.staggerOrder === 'value') {
+    const indexed = marks.map((m, i) => ({ mark: m, idx: i }));
+    indexed.sort((a, b) => {
+      const av = getMarkPrimaryValue(a.mark);
+      const bv = getMarkPrimaryValue(b.mark);
+      return av - bv;
+    });
+    for (let i = 0; i < indexed.length; i++) {
+      const m = indexed[i].mark;
+      if (m.type === 'rect' && (m as RectMark).stackGroup) continue;
+      m.animationIndex = i;
+    }
+  }
+
+  // Phase 2: For stacked bars/columns, assign the same animationIndex to all segments
+  // sharing a stackGroup so they animate as one contiguous bar per category.
+  // Also compute stackPos (segment position within each group: 0, 1, 2...)
+  // so the renderer can chain segment animations sequentially.
+  const groupIndexMap = new Map<string, number>();
+  const groupStackPos = new Map<string, number>();
+  let nextGroupIndex = 0;
+  for (const mark of marks) {
+    if (mark.type === 'rect' && (mark as RectMark).stackGroup) {
+      const rect = mark as RectMark;
+      const group = rect.stackGroup!;
+      if (!groupIndexMap.has(group)) {
+        groupIndexMap.set(group, nextGroupIndex++);
+      }
+      rect.animationIndex = groupIndexMap.get(group)!;
+      const pos = groupStackPos.get(group) ?? 0;
+      rect.stackPos = pos;
+      groupStackPos.set(group, pos + 1);
+    }
+  }
+}

package/src/compile.ts

@@ -13,18 +13,22 @@
 
 import type {
   AnimationSpec,
+  BinParams,
+  BinTransform,
   ChartLayout,
   ChartSpec,
   CompileOptions,
   CompileTableOptions,
+  EncodingChannel,
   LayerSpec,
   Mark,
-  PointMark,
   Rect,
-  RectMark,
   ResolvedAnnotation,
   ResolvedTheme,
   TableLayout,
+  TimeUnit,
+  TimeUnitTransform,
+  Transform,
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
@@ -43,6 +47,11 @@ import { columnRenderer } from './charts/column';
 import { dotRenderer } from './charts/dot';
 import { areaRenderer, lineRenderer } from './charts/line';
 import { donutRenderer, pieRenderer } from './charts/pie';
+import {
+  assignAnimationIndices,
+  computeMarkObstacles,
+  resolveRendererKey,
+} from './charts/post-process';
 import { type ChartRenderer, getChartRenderer, registerChartRenderer } from './charts/registry';
 import { ruleRenderer } from './charts/rule';
 import { scatterRenderer } from './charts/scatter';
@@ -90,7 +99,7 @@ import type { GraphCompilation } from './graphs/types';
 import { computeAxes } from './layout/axes';
 import { computeDimensions } from './layout/dimensions';
 import { computeGridlines } from './layout/gridlines';
-import { computeScales, type ResolvedScales } from './layout/scales';
+import { computeScales } from './layout/scales';
 import { computeLegend } from './legend/compute';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
@@ -98,93 +107,77 @@ import { computeTooltipDescriptors } from './tooltips/compute';
 import { runTransforms } from './transforms';
 
 // ---------------------------------------------------------------------------
-// Mark obstacles for annotation collision avoidance
+// Encoding sugar expansion (bin, timeUnit on encoding channels)
 // ---------------------------------------------------------------------------
 
 /**
- * Compute bounding rects from marks to use as obstacles for annotation nudging.
+ * Expand encoding-level `bin` and `timeUnit` shorthand into explicit transforms.
  *
- * For band-scale charts (bar, dot): groups marks by band row and returns
- * a single obstacle per row spanning the full band height and x-range.
+ * Vega-Lite allows `encoding.x.bin: true` as sugar for a BinTransform.
+ * This function detects those shorthands, generates the corresponding transforms,
+ * updates encoding field references to the output field names, and prepends the
+ * transforms to the spec's transform array.
  *
- * For other charts (column, scatter): returns individual mark bounds so
- * annotations avoid overlapping any visible data mark.
+ * Mutates nothing; returns a new spec object (shallow copy).
  */
-function computeMarkObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
-  // Band-scale y-axis: group marks by row for efficient obstacle computation
-  if (scales.y?.type === 'band') {
-    return computeBandRowObstacles(marks, scales);
-  }
+export function expandEncodingSugar(spec: Record<string, unknown>): Record<string, unknown> {
+  const encoding = spec.encoding as Record<string, EncodingChannel | undefined> | undefined;
+  if (!encoding) return spec;
+
+  const generatedTransforms: Transform[] = [];
+  const updatedEncoding = { ...encoding };
+  let changed = false;
+
+  for (const channel of Object.keys(encoding)) {
+    const ch = encoding[channel];
+    if (!ch || !ch.field) continue;
+
+    // Expand bin shorthand
+    if (ch.bin != null && ch.bin !== false) {
+      const field = ch.field;
+      const outputField = `bin_${field}`;
+      const binTransform: BinTransform = {
+        bin: ch.bin === true ? true : (ch.bin as BinParams),
+        field,
+        as: outputField,
+      };
+      generatedTransforms.push(binTransform);
 
-  // All other charts: use individual rect/point mark bounds as obstacles
-  const obstacles: Rect[] = [];
-  for (const mark of marks) {
-    if (mark.type === 'rect') {
-      const rm = mark as RectMark;
-      obstacles.push({ x: rm.x, y: rm.y, width: rm.width, height: rm.height });
-    } else if (mark.type === 'point') {
-      const pm = mark as PointMark;
-      obstacles.push({
-        x: pm.cx - pm.r,
-        y: pm.cy - pm.r,
-        width: pm.r * 2,
-        height: pm.r * 2,
-      });
+      // Update encoding to reference binned output field, remove bin property
+      const { bin: _bin, ...rest } = ch;
+      updatedEncoding[channel] = { ...rest, field: outputField } as EncodingChannel;
+      changed = true;
     }
-  }
-  return obstacles;
-}
 
-/** Group band-scale marks by row, returning one obstacle per band. */
-function computeBandRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
-  const rows = new Map<number, { minX: number; maxX: number; bandY: number }>();
-
-  for (const mark of marks) {
-    let cy: number;
-    let left: number;
-    let right: number;
-
-    if (mark.type === 'point') {
-      const pm = mark as PointMark;
-      cy = pm.cy;
-      left = pm.cx - pm.r;
-      right = pm.cx + pm.r;
-    } else if (mark.type === 'rect') {
-      const rm = mark as RectMark;
-      cy = rm.y + rm.height / 2;
-      left = rm.x;
-      right = rm.x + rm.width;
-    } else {
-      continue;
-    }
+    // Expand timeUnit shorthand (read from updated encoding in case bin already ran)
+    const current = updatedEncoding[channel] ?? ch;
+    if (current.timeUnit) {
+      const field = current.field;
+      const unit = current.timeUnit as TimeUnit;
+      const outputField = `${unit}_${field}`;
+      const timeUnitTransform: TimeUnitTransform = {
+        timeUnit: unit,
+        field,
+        as: outputField,
+      };
+      generatedTransforms.push(timeUnitTransform);
 
-    // Round cy to group marks on the same band
-    const key = Math.round(cy);
-    const existing = rows.get(key);
-    if (existing) {
-      existing.minX = Math.min(existing.minX, left);
-      existing.maxX = Math.max(existing.maxX, right);
-    } else {
-      rows.set(key, { minX: left, maxX: right, bandY: cy });
+      // Update encoding to reference timeUnit output field, remove timeUnit property
+      const { timeUnit: _tu, ...rest } = current;
+      updatedEncoding[channel] = { ...rest, field: outputField } as EncodingChannel;
+      changed = true;
     }
   }
 
-  // Get bandwidth from the band scale
-  const bandScale = scales.y!.scale as { bandwidth?: () => number };
-  const bandwidth = bandScale.bandwidth?.() ?? 0;
-  if (bandwidth === 0) return [];
+  if (!changed) return spec;
 
-  const obstacles: Rect[] = [];
-  for (const { minX, maxX, bandY } of rows.values()) {
-    obstacles.push({
-      x: minX,
-      y: bandY - bandwidth / 2,
-      width: maxX - minX,
-      height: bandwidth,
-    });
-  }
-
-  return obstacles;
+  // Prepend generated transforms before any user-defined transforms
+  const existingTransforms = (spec.transform as Transform[] | undefined) ?? [];
+  return {
+    ...spec,
+    encoding: updatedEncoding,
+    transform: [...generatedTransforms, ...existingTransforms],
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -204,8 +197,15 @@ function computeBandRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[]
  * @throws Error if spec is invalid or not a chart type.
  */
 export function compileChart(spec: unknown, options: CompileOptions): ChartLayout {
+  // Expand encoding-level bin/timeUnit sugar before validation + normalization.
+  // This converts shorthand (e.g. encoding.x.bin: true) into explicit transforms.
+  const expandedSpec =
+    spec && typeof spec === 'object' && !Array.isArray(spec)
+      ? expandEncodingSugar(spec as Record<string, unknown>)
+      : spec;
+
   // Validate + normalize
-  const { spec: normalized } = compileSpec(spec);
+  const { spec: normalized } = compileSpec(expandedSpec);
 
   if ('type' in normalized && (normalized as unknown as Record<string, unknown>).type === 'table') {
     throw new Error('compileChart received a table spec. Use compileTable instead.');
@@ -222,10 +222,15 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 
   let chartSpec = normalized as NormalizedChartSpec;
 
+  // Resolve watermark: explicit spec value wins, then options fallback, then default true.
+  const rawWatermark = (expandedSpec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? chartSpec.watermark : (options.watermark ?? true);
+
   // Run data transforms (filter, bin, calculate, timeUnit) before any other data processing.
-  // Transforms are defined on the original spec, not the normalized spec, since
-  // NormalizedChartSpec doesn't carry the transform field.
-  const rawTransforms = (spec as Record<string, unknown>).transform as
+  // Transforms are defined on the expanded spec (which includes any auto-generated
+  // transforms from encoding-level bin/timeUnit sugar), not the normalized spec,
+  // since NormalizedChartSpec doesn't carry the transform field.
+  const rawTransforms = (expandedSpec as Record<string, unknown>).transform as
     | import('@opendata-ai/openchart-core').Transform[]
     | undefined;
   if (rawTransforms && rawTransforms.length > 0) {
@@ -237,8 +242,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const heightClass = getHeightClass(options.height);
   const strategy = getLayoutStrategy(breakpoint, heightClass);
 
-  // Apply breakpoint-conditional overrides from the original spec
-  const rawSpec = spec as Record<string, unknown>;
+  // Apply breakpoint-conditional overrides from the expanded spec
+  const rawSpec = expandedSpec as Record<string, unknown>;
   const overrides = rawSpec.overrides as
     | Partial<
         Record<
@@ -306,10 +311,10 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     width: options.width,
     height: options.height,
   };
-  const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea);
+  const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea, watermark);
 
   // Compute dimensions (accounts for chrome + legend + responsive strategy)
-  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy);
+  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy, watermark);
   const chartArea = dims.chartArea;
 
   // Recompute legend bounds relative to actual chart area.
@@ -332,7 +337,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
         break;
     }
   }
-  const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea);
+  const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea, watermark);
 
   // Apply data filtering after legend (so legend retains all series), but before
   // scale computation (so hidden/clipped data doesn't affect domains or marks).
@@ -404,26 +409,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
 
   // Get chart renderer and compute marks (using filtered data).
-  // For 'bar' mark, resolve orientation to pick horizontal vs vertical renderer.
-  // For 'arc' mark, resolve innerRadius to pick pie vs donut renderer.
-  let rendererKey = renderSpec.markType as string;
-  if (rendererKey === 'bar') {
-    // Infer orientation from encoding: if x is quantitative and y is categorical, horizontal (default)
-    // If x is categorical and y is quantitative, vertical (old 'column')
-    const xType = renderSpec.encoding.x?.type;
-    const yType = renderSpec.encoding.y?.type;
-    const isVertical =
-      (xType === 'nominal' || xType === 'ordinal' || xType === 'temporal') &&
-      yType === 'quantitative';
-    if (isVertical) {
-      rendererKey = 'bar:vertical';
-    }
-  } else if (rendererKey === 'arc') {
-    const innerRadius = renderSpec.markDef.innerRadius;
-    if (innerRadius && innerRadius > 0) {
-      rendererKey = 'arc:donut';
-    }
-  }
+  const rendererKey = resolveRendererKey(
+    renderSpec.markType,
+    renderSpec.encoding,
+    renderSpec.markDef,
+  );
   const renderer = getChartRenderer(rendererKey);
   const marks: Mark[] = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme) : [];
 
@@ -444,14 +434,16 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Add brand watermark as an obstacle so annotations avoid overlapping it.
   // The brand is right-aligned on the same baseline as the first bottom chrome element,
   // offset below the chart area by x-axis extent (tick labels + axis title).
-  const brandPadding = theme.spacing.padding;
-  const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
-  const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
-  const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
-  const brandY = firstBottomChrome
-    ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
-    : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
-  obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
+  if (watermark) {
+    const brandPadding = theme.spacing.padding;
+    const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
+    const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
+    const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
+    const brandY = firstBottomChrome
+      ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
+      : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
+    obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
+  }
   const annotations: ResolvedAnnotation[] = computeAnnotations(
     chartSpec,
     scales,
@@ -485,44 +477,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   );
 
   // Assign animationIndex for stagger ordering when animation is enabled
-  // Assign animationIndex for value-based stagger ordering. Skip stacked rects
-  // since they get group-based indices below (avoids wasted work that gets overwritten).
-  if (resolvedAnimation?.enabled && resolvedAnimation.staggerOrder === 'value') {
-    const indexed = marks.map((m, i) => ({ mark: m, idx: i }));
-    indexed.sort((a, b) => {
-      const av = getMarkPrimaryValue(a.mark);
-      const bv = getMarkPrimaryValue(b.mark);
-      return av - bv;
-    });
-    for (let i = 0; i < indexed.length; i++) {
-      const m = indexed[i].mark;
-      if (m.type === 'rect' && (m as RectMark).stackGroup) continue;
-      m.animationIndex = i;
-    }
-  }
-
-  // For stacked bars/columns, assign the same animationIndex to all segments
-  // sharing a stackGroup so they animate as one contiguous bar per category.
-  // Also compute stackPos (segment position within each group: 0, 1, 2...)
-  // so the renderer can chain segment animations sequentially.
-  if (resolvedAnimation?.enabled) {
-    const groupIndexMap = new Map<string, number>();
-    const groupStackPos = new Map<string, number>();
-    let nextGroupIndex = 0;
-    for (const mark of marks) {
-      if (mark.type === 'rect' && (mark as RectMark).stackGroup) {
-        const rect = mark as RectMark;
-        const group = rect.stackGroup!;
-        if (!groupIndexMap.has(group)) {
-          groupIndexMap.set(group, nextGroupIndex++);
-        }
-        rect.animationIndex = groupIndexMap.get(group)!;
-        const pos = groupStackPos.get(group) ?? 0;
-        rect.stackPos = pos;
-        groupStackPos.set(group, pos + 1);
-      }
-    }
-  }
+  assignAnimationIndices(marks, resolvedAnimation);
 
   return {
     area: chartArea,
@@ -547,26 +502,10 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       height: options.height,
     },
     animation: resolvedAnimation,
+    watermark,
   };
 }
 
-/** Extract the primary quantitative value from a mark for value-based stagger ordering. */
-function getMarkPrimaryValue(mark: Mark): number {
-  switch (mark.type) {
-    case 'rect':
-      return mark.height; // bar height is the primary value encoding
-    case 'point':
-      return mark.cy; // y position for scatter
-    case 'arc':
-      return mark.endAngle - mark.startAngle; // arc angle extent
-    case 'line':
-    case 'area':
-      return 0; // series marks don't have individual values
-    default:
-      return 0;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Layer compilation
 // ---------------------------------------------------------------------------
@@ -656,6 +595,7 @@ function buildPrimarySpec(leaves: ChartSpec[], layerSpec: LayerSpec): ChartSpec
     responsive: layerSpec.responsive ?? leaves[0].responsive,
     theme: layerSpec.theme ?? leaves[0].theme,
     darkMode: layerSpec.darkMode ?? leaves[0].darkMode,
+    watermark: layerSpec.watermark ?? leaves[0].watermark,
     hiddenSeries: layerSpec.hiddenSeries ?? leaves[0].hiddenSeries,
   };
 
@@ -697,7 +637,11 @@ export function compileTable(spec: unknown, options: CompileTableOptions): Table
     theme = adaptTheme(theme);
   }
 
-  return compileTableLayout(tableSpec, options, theme);
+  // Resolve watermark: spec-level wins, then options, then default true
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? tableSpec.watermark : (options.watermark ?? true);
+
+  return compileTableLayout({ ...tableSpec, watermark }, options, theme);
 }
 
 // ---------------------------------------------------------------------------