@opendata-ai/openchart-engine 6.10.0 → 6.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.10.0",
+  "version": "6.12.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.10.0",
+    "@opendata-ai/openchart-core": "6.12.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -73,6 +73,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     labels: { density: 'auto', format: '', prefix: '' },
     hiddenSeries: [],
     seriesStyles: {},
+    watermark: true,
   };
 }
 
@@ -102,6 +103,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     labels: { density: 'auto', format: '', prefix: '' },
     hiddenSeries: [],
     seriesStyles: {},
+    watermark: true,
   };
 }
 
@@ -133,5 +135,6 @@ export function makeScatterSpec(): NormalizedChartSpec {
     labels: { density: 'auto', format: '', prefix: '' },
     hiddenSeries: [],
     seriesStyles: {},
+    watermark: true,
   };
 }

package/src/charts/bar/compute.ts

@@ -10,12 +10,13 @@ import type {
   ConditionalValueDef,
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber } from '@opendata-ai/openchart-core';
+import { abbreviateNumber, formatNumber, isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
@@ -339,11 +340,14 @@ function computeSimpleBars(
     const bandY = yScale(category);
     if (bandY === undefined) continue;
 
-    let color: string;
+    let color: string | GradientDef;
     if (conditionalColor) {
-      color = String(
-        resolveConditionalValue(row, conditionalColor) ?? getColor(scales, '__default__'),
-      );
+      const resolved = resolveConditionalValue(row, conditionalColor);
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else {
+        color = getColor(scales, '__default__');
+      }
     } else if (sequentialColor) {
       color = getSequentialColor(scales, value);
     } else {

package/src/charts/bar/labels.ts

@@ -20,6 +20,7 @@ import type {
 import {
   buildD3Formatter,
   estimateTextWidth,
+  getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
 
@@ -141,7 +142,7 @@ export function computeBarLabels(
     } else {
       // Outside: just past the bar's right edge
       anchorX = mark.x + mark.width + LABEL_PADDING;
-      fill = mark.fill;
+      fill = getRepresentativeColor(mark.fill);
       textAnchor = 'start';
     }
 

package/src/charts/column/compute.ts

@@ -14,12 +14,13 @@ import type {
   ConditionalValueDef,
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber } from '@opendata-ai/openchart-core';
+import { abbreviateNumber, formatNumber, isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -169,11 +170,14 @@ function computeSimpleColumns(
     const bandX = xScale(category);
     if (bandX === undefined) continue;
 
-    let color: string;
+    let color: string | GradientDef;
     if (conditionalColor) {
-      color = String(
-        resolveConditionalValue(row, conditionalColor) ?? getColor(scales, '__default__'),
-      );
+      const resolved = resolveConditionalValue(row, conditionalColor);
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else {
+        color = getColor(scales, '__default__');
+      }
     } else if (sequentialColor) {
       color = getSequentialColor(scales, value);
     } else {

package/src/charts/column/labels.ts

@@ -20,6 +20,7 @@ import type {
 import {
   buildD3Formatter,
   estimateTextWidth,
+  getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
 
@@ -99,7 +100,7 @@ export function computeColumnLabels(
         fontFamily: 'system-ui, -apple-system, sans-serif',
         fontSize: LABEL_FONT_SIZE,
         fontWeight: LABEL_FONT_WEIGHT,
-        fill: mark.fill,
+        fill: getRepresentativeColor(mark.fill),
         lineHeight: 1.2,
         textAnchor: 'middle',
         dominantBaseline: isNegative ? 'hanging' : 'auto',

package/src/charts/dot/labels.ts

@@ -17,7 +17,11 @@ import type {
   Rect,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import {
+  estimateTextWidth,
+  getRepresentativeColor,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -74,7 +78,7 @@ export function computeDotLabels(
         fontFamily: 'system-ui, -apple-system, sans-serif',
         fontSize: LABEL_FONT_SIZE,
         fontWeight: LABEL_FONT_WEIGHT,
-        fill: mark.fill,
+        fill: getRepresentativeColor(mark.fill),
         lineHeight: 1.2,
         textAnchor: 'start',
         dominantBaseline: 'central',

package/src/charts/line/area.ts

@@ -7,6 +7,7 @@
  */
 
 import type { AreaMark, DataRow, Encoding, MarkAria, Rect } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 import type { ScaleLinear } from 'd3-scale';
 import { area, line, stack, stackOffsetNone, stackOrderNone } from 'd3-shape';
 
@@ -122,7 +123,7 @@ function computeSingleArea(
       topPath: topPathStr,
       fill: color,
       fillOpacity: DEFAULT_FILL_OPACITY,
-      stroke: color,
+      stroke: getRepresentativeColor(color),
       strokeWidth: 2,
       seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
       data: validPoints.map((p) => p.row),
@@ -258,7 +259,7 @@ function computeStackedArea(
       topPath: topPathStr,
       fill: color,
       fillOpacity: 0.7, // Higher opacity for stacked so layers are visible
-      stroke: color,
+      stroke: getRepresentativeColor(color),
       strokeWidth: 1,
       seriesKey,
       data: layer.map((d) => {

package/src/charts/line/compute.ts

@@ -10,12 +10,14 @@
 import type {
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   LineMark,
   MarkAria,
   PointMark,
   Rect,
 } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 import { line } from 'd3-shape';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
@@ -68,9 +70,10 @@ export function computeLineMarks(
 
   for (const [seriesKey, rows] of groups) {
     // For sequential color, use a mid-range color for the line stroke
-    const color = isSequentialColor
+    const color: string | GradientDef = isSequentialColor
       ? getSequentialColor(scales, _getMidValue(rows, sequentialColorField!))
       : getColor(scales, seriesKey);
+    const strokeColor = getRepresentativeColor(color);
 
     // Sort rows by x-axis field so lines draw left-to-right
     const sortedRows = sortByField(rows, xChannel.field);
@@ -165,7 +168,7 @@ export function computeLineMarks(
       type: 'line',
       points: allPoints,
       path: combinedPath,
-      stroke: color,
+      stroke: strokeColor,
       strokeWidth: styleOverride?.strokeWidth ?? DEFAULT_STROKE_WIDTH,
       strokeDasharray,
       opacity: styleOverride?.opacity,

package/src/charts/pie/compute.ts

@@ -8,17 +8,21 @@
 
 import type {
   ArcMark,
+  ConditionalValueDef,
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   Rect,
 } from '@opendata-ai/openchart-core';
+import { isConditionalDef, isGradientDef } from '@opendata-ai/openchart-core';
 import type { PieArcDatum } from 'd3-shape';
 import { arc as d3Arc, pie as d3Pie } from 'd3-shape';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
+import { resolveConditionalValue } from '../../transforms/conditional';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -109,6 +113,10 @@ export function computePieMarks(
   const valueChannel = encoding.y ?? encoding.x;
   const categoryField =
     encoding.color && 'field' in encoding.color ? encoding.color.field : undefined;
+  const conditionalColor =
+    encoding.color && isConditionalDef(encoding.color)
+      ? (encoding.color as ConditionalValueDef)
+      : undefined;
 
   if (!valueChannel) return [];
 
@@ -190,9 +198,22 @@ export function computePieMarks(
     const arcDatum = arcs[i];
     const slice = arcDatum.data;
 
-    // Get color from scale or default palette
-    let color: string;
-    if (scales.color && categoryField) {
+    // Get color: conditional (supports gradients) > scale > default palette
+    let color: string | GradientDef;
+    if (conditionalColor) {
+      const resolved = resolveConditionalValue(
+        slice.originalRow as Record<string, unknown>,
+        conditionalColor,
+      );
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else if (scales.color && categoryField) {
+        const colorScale = scales.color.scale as (v: string) => string;
+        color = colorScale(slice.label);
+      } else {
+        color = DEFAULT_PALETTE[i % DEFAULT_PALETTE.length];
+      }
+    } else if (scales.color && categoryField) {
       const colorScale = scales.color.scale as (v: string) => string;
       color = colorScale(slice.label);
     } else {

package/src/charts/rule/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Encoding, Mark, MarkAria, Rect, RuleMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -84,9 +85,11 @@ export function computeRuleMarks(
       if (y2Val != null) y2 = y2Val;
     }
 
-    const color = colorField
-      ? getColor(scales, String(row[colorField] ?? '__default__'))
-      : getColor(scales, '__default__');
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
 
     const strokeDashEncoding =
       encoding.strokeDash && 'field' in encoding.strokeDash ? encoding.strokeDash : undefined;

package/src/charts/scatter/compute.ts

@@ -10,6 +10,7 @@
 import type {
   Encoding,
   FieldType,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   PointMark,
@@ -139,7 +140,7 @@ export function computeScatterMarks(
     if (cx === undefined || cy === undefined) continue;
 
     const category = colorField && !isSequentialColor ? String(row[colorField] ?? '') : undefined;
-    let color: string;
+    let color: string | GradientDef;
     if (isSequentialColor && colorField) {
       const val = Number(row[colorField]);
       color = Number.isFinite(val)

package/src/charts/text/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Encoding, Mark, MarkAria, TextMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -52,9 +53,11 @@ export function computeTextMarks(
     const text = String(row[textChannel.field] ?? '');
     if (!text) continue;
 
-    const color = colorField
-      ? getColor(scales, String(row[colorField] ?? '__default__'))
-      : getColor(scales, '__default__');
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
 
     const fontSize = sizeEncoding
       ? Math.max(8, Math.min(48, Number(row[sizeEncoding.field]) || 12))

package/src/charts/tick/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Encoding, Mark, MarkAria, Rect, TickMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -48,9 +49,11 @@ export function computeTickMarks(
     const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
     if (xVal == null || yVal == null) continue;
 
-    const color = colorField
-      ? getColor(scales, String(row[colorField] ?? '__default__'))
-      : getColor(scales, '__default__');
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
 
     const aria: MarkAria = {
       label: `${row[xChannel.field]}, ${row[yChannel.field]}`,

package/src/charts/utils.ts

@@ -5,7 +5,7 @@
  * data grouping, color lookup, and shared constants.
  */
 
-import type { DataRow } from '@opendata-ai/openchart-core';
+import type { DataRow, GradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
 import type { D3Scale, ResolvedScales } from '../layout/scales';
 
@@ -143,7 +143,7 @@ export function getColor(
   key: string,
   _index?: number,
   fallback: string = DEFAULT_COLOR,
-): string {
+): string | GradientDef {
   if (scales.color && key !== '__default__') {
     const colorScale = scales.color.scale as (v: string) => string;
     return colorScale(key);
@@ -159,7 +159,7 @@ export function getSequentialColor(
   scales: ResolvedScales,
   value: number,
   fallback: string = DEFAULT_COLOR,
-): string {
+): string | GradientDef {
   if (scales.color?.type === 'sequential') {
     const colorScale = scales.color.scale as unknown as (v: number) => string;
     return colorScale(value);

package/src/compile.ts

@@ -222,6 +222,10 @@ 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 = (spec 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.
@@ -306,10 +310,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 +336,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).
@@ -386,8 +390,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     }
   }
 
-  // Set default color for single-series charts (no color encoding)
-  scales.defaultColor = theme.colors.categorical[0];
+  // Set default color for single-series charts. If the user set a fill on the mark def
+  // (string or gradient), that takes priority over the theme's first categorical color.
+  scales.defaultColor = chartSpec.markDef.fill ?? theme.colors.categorical[0];
 
   // Arc charts (pie/donut) don't use axes or gridlines
   const isRadial = chartSpec.markType === 'arc';
@@ -443,14 +448,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,
@@ -546,6 +553,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       height: options.height,
     },
     animation: resolvedAnimation,
+    watermark,
   };
 }
 
@@ -655,6 +663,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,
   };
 
@@ -696,7 +705,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);
 }
 
 // ---------------------------------------------------------------------------

package/src/compiler/__tests__/normalize.test.ts

@@ -1,12 +1,15 @@
 import type {
   ChartSpec,
   GraphSpec,
+  LayerSpec,
   RangeAnnotation,
   RefLineAnnotation,
+  SankeySpec,
   TableSpec,
   TextAnnotation,
 } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
+import type { NormalizedSankeySpec } from '../../sankey/types';
 import { normalizeSpec } from '../normalize';
 import type { NormalizedChartSpec, NormalizedGraphSpec, NormalizedTableSpec } from '../types';
 
@@ -52,6 +55,17 @@ describe('normalizeSpec', () => {
       });
     });
 
+    it('watermark defaults to true when not specified', () => {
+      const result = normalizeSpec(lineSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: ChartSpec = { ...lineSpec, watermark: false };
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(false);
+    });
+
     it('preserves explicit values', () => {
       const spec: ChartSpec = {
         ...lineSpec,
@@ -205,6 +219,27 @@ describe('normalizeSpec', () => {
       expect(result.responsive).toBe(true);
       expect(result.darkMode).toBe('off');
     });
+
+    it('watermark defaults to true when not specified', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+      };
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+        watermark: false,
+      };
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.watermark).toBe(false);
+    });
   });
 
   describe('graph spec normalization', () => {
@@ -221,5 +256,80 @@ describe('normalizeSpec', () => {
       expect(result.annotations).toEqual([]);
       expect(result.darkMode).toBe('off');
     });
+
+    it('watermark defaults to true when not specified', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+      };
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+        watermark: false,
+      };
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('sankey spec normalization', () => {
+    const baseSankeySpec: SankeySpec = {
+      type: 'sankey',
+      data: [{ source: 'A', target: 'B', value: 10 }],
+      encoding: {
+        source: { field: 'source' },
+        target: { field: 'target' },
+        value: { field: 'value' },
+      },
+    };
+
+    it('watermark defaults to true when not specified', () => {
+      const result = normalizeSpec(baseSankeySpec) as NormalizedSankeySpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: SankeySpec = { ...baseSankeySpec, watermark: false };
+      const result = normalizeSpec(spec) as NormalizedSankeySpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('layer spec normalization', () => {
+    const baseLeaf: ChartSpec = {
+      mark: 'line',
+      data: [{ x: 1, y: 2 }],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+      },
+    };
+
+    it('watermark defaults to true for layer leaves', () => {
+      const layerSpec: LayerSpec = { layer: [baseLeaf] };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('layer-level watermark: false propagates to leaves', () => {
+      const layerSpec: LayerSpec = { layer: [baseLeaf], watermark: false };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(false);
+    });
+
+    it('leaf-level watermark overrides layer-level', () => {
+      const leaf: ChartSpec = { ...baseLeaf, watermark: true };
+      const layerSpec: LayerSpec = { layer: [leaf], watermark: false };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      // Leaf explicitly sets true, which should be preserved
+      expect(result.watermark).toBe(true);
+    });
   });
 });