@opendata-ai/openchart-engine 7.7.0 → 7.9.0

package/src/charts/dot/compute.ts

@@ -20,6 +20,7 @@ import type {
 } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { getColor, getSequentialColor, groupByField } from '../utils';
@@ -77,9 +78,11 @@ export function computeDotMarks(
   const isSequentialColor = colorEnc?.type === 'quantitative';
   const colorField = isSequentialColor ? undefined : colorEnc?.field;
 
+  let marks: (PointMark | RectMark)[];
+
   // Multi-series (categorical): dumbbell chart with connecting bars
   if (colorField) {
-    return computeDumbbellMarks(
+    marks = computeDumbbellMarks(
       spec.data,
       xChannel.field,
       yChannel.field,
@@ -89,20 +92,34 @@ export function computeDotMarks(
       bandwidth,
       scales,
     );
+  } else {
+    // Single series: lollipop stems from baseline
+    marks = computeLollipopMarks(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      xScale,
+      yScale,
+      bandwidth,
+      baseline,
+      scales,
+      isSequentialColor,
+    );
   }
 
-  // Single series: lollipop stems from baseline
-  return computeLollipopMarks(
-    spec.data,
-    xChannel.field,
-    yChannel.field,
-    xScale,
-    yScale,
-    bandwidth,
-    baseline,
-    scales,
-    isSequentialColor,
-  );
+  // Stamp keys on point marks (skip rect stems/connectors)
+  const pointMarks = marks.filter((m): m is PointMark => m.type === 'point');
+  const rawKeys = pointMarks.map((m) => {
+    const cat = serializeKeyValue(m.data[yChannel.field]);
+    const series = colorField ? String(m.data[colorField] ?? '') : '';
+    return series ? `${series}|${cat}` : cat;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < pointMarks.length; i++) {
+    pointMarks[i].key = keys[i];
+  }
+
+  return marks;
 }
 
 // ---------------------------------------------------------------------------

package/src/charts/line/area.ts

@@ -24,6 +24,7 @@ import {
   stackOrderNone,
 } from 'd3-shape';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { getColor, scaleValue, sortByField } from '../utils';
@@ -235,8 +236,16 @@ function computeSingleArea(
       fillOpacity = 1;
     }
 
+    const keyField = encoding.key && 'field' in encoding.key ? encoding.key.field : undefined;
+    const rawPointKeys = validPoints.map((p) =>
+      keyField ? serializeKeyValue(p.row[keyField]) : serializeKeyValue(p.row[xChannel.field]),
+    );
+
     marks.push({
       type: 'area',
+      key: seriesKey === '__default__' ? 'area' : seriesKey,
+      pointKeys: dedupeKeys(rawPointKeys),
+      interpolate: spec.markDef.interpolate ?? 'monotone',
       topPoints,
       bottomPoints,
       path: pathStr,
@@ -402,8 +411,13 @@ function computeStackedArea(
       fillOpacity = 1;
     }
 
+    const rawPointKeys = validPoints.map((_p, idx) => serializeKeyValue(layer[idx]?.data.__x__));
+
     marks.push({
       type: 'area',
+      key: seriesKey,
+      pointKeys: dedupeKeys(rawPointKeys),
+      interpolate: spec.markDef.interpolate ?? 'monotone',
       topPoints,
       bottomPoints,
       path: pathStr,
@@ -464,6 +478,12 @@ export function computeAreaMarks(
     marks = computeSingleArea(spec, scales, chartArea);
   }
 
+  // Dedupe area mark keys
+  const areaKeys = dedupeKeys(marks.map((m) => m.key!));
+  marks.forEach((m, i) => {
+    m.key = areaKeys[i];
+  });
+
   const highlight = spec.highlight ?? [];
   if (highlight.length > 0) {
     const highlightSet = new Set(highlight);

package/src/charts/line/compute.ts

@@ -20,6 +20,7 @@ import type {
 import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 import { line } from 'd3-shape';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { getColor, getSequentialColor, groupByField, scaleValue, sortByField } from '../utils';
@@ -183,8 +184,16 @@ export function computeLineMarks(
     // Create the LineMark with the combined path points.
     // The points array includes all valid points across all segments.
     // dataPoints carries pixel coordinates + original data for voronoi tooltip overlay.
+    const keyField = encoding.key && 'field' in encoding.key ? encoding.key.field : undefined;
+    const rawPointKeys = pointsWithData.map((p) =>
+      keyField ? serializeKeyValue(p.row[keyField]) : serializeKeyValue(p.row[xChannel.field]),
+    );
+
     const lineMark: LineMark = {
       type: 'line',
+      key: seriesStyleKey ?? 'series',
+      pointKeys: dedupeKeys(rawPointKeys),
+      interpolate: spec.markDef.interpolate ?? 'monotone',
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
@@ -242,9 +251,15 @@ export function computeLineMarks(
         // color — no white halo, no hollow ring. Marked decorative because the
         // data point already exists on the line and gets described by the a11y
         // data table; the dot is purely visual.
+        const pointKey = keyField
+          ? serializeKeyValue(p.row[keyField])
+          : seriesStyleKey
+            ? `${seriesStyleKey}|${serializeKeyValue(p.row[xChannel.field])}`
+            : serializeKeyValue(p.row[xChannel.field]);
         if (isSingleEndpoint) {
           bucket.push({
             type: 'point',
+            key: pointKey,
             cx: p.x,
             cy: p.y,
             r: 3.5,
@@ -259,6 +274,7 @@ export function computeLineMarks(
         }
         const pointMark: PointMark = {
           type: 'point',
+          key: pointKey,
           cx: p.x,
           cy: p.y,
           r: visible ? DEFAULT_POINT_RADIUS : 0,
@@ -276,7 +292,25 @@ export function computeLineMarks(
     }
   }
 
-  return [...mutedMarks, ...highlightedMarks];
+  const allMarks = [...mutedMarks, ...highlightedMarks];
+
+  // Dedupe series-level keys across all line marks
+  const lineMarks = allMarks.filter((m): m is LineMark => m.type === 'line');
+  const lineKeys = dedupeKeys(lineMarks.map((m) => m.key!));
+  lineMarks.forEach((m, i) => {
+    m.key = lineKeys[i];
+  });
+
+  // Dedupe point mark keys
+  const pointMarks = allMarks.filter((m): m is PointMark => m.type === 'point');
+  if (pointMarks.length > 0) {
+    const pointKeys = dedupeKeys(pointMarks.map((m) => m.key ?? ''));
+    pointMarks.forEach((m, i) => {
+      m.key = pointKeys[i];
+    });
+  }
+
+  return allMarks;
 }
 
 // ---------------------------------------------------------------------------

package/src/charts/line/curves.ts

@@ -1,13 +1,18 @@
 /**
- * Curve interpolation mapping.
+ * Curve interpolation mapping and path builders.
  *
  * Maps Vega-Lite-style interpolation strings to d3-shape curve factories.
  * Used by both line and area chart computations.
+ *
+ * Also exports pure path-builder helpers (`buildLinePath`, `buildAreaPath`)
+ * so downstream consumers (e.g. transition interpolators) can reconstruct
+ * SVG paths from point arrays without pulling in chart-specific code.
  */
 
-import type { MarkDef } from '@opendata-ai/openchart-core';
+import type { MarkDef, Point } from '@opendata-ai/openchart-core';
 import type { CurveFactory } from 'd3-shape';
 import {
+  area,
   curveBasis,
   curveCardinal,
   curveLinear,
@@ -16,6 +21,7 @@ import {
   curveStep,
   curveStepAfter,
   curveStepBefore,
+  line,
 } from 'd3-shape';
 
 /** Map of interpolation string names to d3 curve factories. */
@@ -38,3 +44,42 @@ export function resolveCurve(interpolate?: MarkDef['interpolate']): CurveFactory
   if (!interpolate) return curveMonotoneX;
   return CURVE_MAP[interpolate] ?? curveMonotoneX;
 }
+
+/**
+ * Build an SVG path string from an array of points using d3 line generator.
+ * Accepts an optional interpolation string (defaults to 'monotone').
+ */
+export function buildLinePath(points: Point[], interpolate?: string): string {
+  if (points.length === 0) return '';
+  const curve = resolveCurve(interpolate as MarkDef['interpolate']);
+  const generator = line<Point>()
+    .x((d) => d.x)
+    .y((d) => d.y)
+    .curve(curve);
+  return generator(points) ?? '';
+}
+
+/**
+ * Build an SVG path string for a filled area from top and bottom point arrays.
+ * Accepts an optional interpolation string (defaults to 'monotone').
+ */
+export function buildAreaPath(
+  topPoints: Point[],
+  bottomPoints: Point[],
+  interpolate?: string,
+): string {
+  if (topPoints.length === 0) return '';
+  const curve = resolveCurve(interpolate as MarkDef['interpolate']);
+  // Pair top and bottom points for the area generator
+  const paired = topPoints.map((tp, i) => ({
+    x: tp.x,
+    yTop: tp.y,
+    yBottom: bottomPoints[i]?.y ?? 0,
+  }));
+  const generator = area<{ x: number; yTop: number; yBottom: number }>()
+    .x((d) => d.x)
+    .y0((d) => d.yBottom)
+    .y1((d) => d.yTop)
+    .curve(curve);
+  return generator(paired) ?? '';
+}

package/src/charts/pie/compute.ts

@@ -20,6 +20,7 @@ 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 { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { resolveConditionalValue } from '../../transforms/conditional';
@@ -252,5 +253,17 @@ export function computePieMarks(
     });
   }
 
+  // Stamp keys: slice label (category name) as the natural identity
+  const rawKeys = marks.map((m) => {
+    const label = categoryField
+      ? String(m.data[categoryField] ?? '')
+      : String(m.data.label ?? m.data.name ?? m.data.category ?? '');
+    return serializeKeyValue(label);
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
   return marks;
 }

package/src/charts/post-process.ts

@@ -188,11 +188,11 @@ export function assignAnimationIndices(
   marks: Mark[],
   animation: ResolvedAnimation | undefined,
 ): void {
-  if (!animation?.enabled) return;
+  if (!animation?.enter) 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') {
+  if (animation.enter.staggerOrder === 'value') {
     const indexed = marks.map((m, i) => ({ mark: m, idx: i }));
     indexed.sort((a, b) => {
       const av = getMarkPrimaryValue(a.mark);

package/src/charts/rule/index.ts

@@ -9,6 +9,7 @@
 import type { Encoding, Mark, MarkAria, Rect, RuleMarkLayout } from '@opendata-ai/openchart-core';
 import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import type { ChartRenderer } from '../registry';
@@ -119,6 +120,14 @@ export function computeRuleMarks(
     });
   }
 
+  // Stamp keys: position-defining values, fall back to index
+  const posField = xChannel?.field ?? yChannel?.field;
+  const rawKeys = marks.map((m, i) => (posField ? serializeKeyValue(m.data[posField]) : String(i)));
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
   return marks;
 }
 

package/src/charts/scatter/compute.ts

@@ -20,6 +20,7 @@ import { max, min } from 'd3-array';
 import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
 import { scaleSqrt } from 'd3-scale';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { getColor, getSequentialColor } from '../utils';
@@ -133,6 +134,8 @@ export function computeScatterMarks(
     sizeScale = scaleSqrt().domain([sizeMin, sizeMax]).range([radiusMin, radiusMax]).clamp(true);
   }
 
+  const keyEnc = encoding.key && 'field' in encoding.key ? encoding.key : undefined;
+  const keyField = keyEnc?.field;
   const marks: PointMark[] = [];
 
   for (const row of spec.data) {
@@ -187,5 +190,17 @@ export function computeScatterMarks(
     });
   }
 
+  // Stamp keys: encoding.key field when set, else seriesKey|x composite
+  const rawKeys = marks.map((m) => {
+    if (keyField) return serializeKeyValue(m.data[keyField]);
+    const cat = colorField ? String(m.data[colorField] ?? '') : '';
+    const xVal = serializeKeyValue(m.data[xChannel.field]);
+    return cat ? `${cat}|${xVal}` : xVal;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
   return marks;
 }

package/src/charts/text/index.ts

@@ -9,6 +9,7 @@
 import type { Encoding, Mark, MarkAria, TextMarkLayout } from '@opendata-ai/openchart-core';
 import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import type { ChartRenderer } from '../registry';
@@ -84,6 +85,14 @@ export function computeTextMarks(
     });
   }
 
+  // Stamp keys: position-defining value, fall back to index
+  const posField = xChannel?.field ?? yChannel?.field;
+  const rawKeys = marks.map((m, i) => (posField ? serializeKeyValue(m.data[posField]) : String(i)));
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
   return marks;
 }
 

package/src/charts/tick/index.ts

@@ -9,6 +9,7 @@
 import type { Encoding, Mark, MarkAria, Rect, TickMarkLayout } from '@opendata-ai/openchart-core';
 import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import type { ChartRenderer } from '../registry';
@@ -76,6 +77,14 @@ export function computeTickMarks(
     });
   }
 
+  // Stamp keys: position-defining value, fall back to index
+  const posField = isHorizontal ? xChannel.field : yChannel.field;
+  const rawKeys = marks.map((m) => serializeKeyValue(m.data[posField]));
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
   return marks;
 }
 

package/src/compile.ts

@@ -967,7 +967,7 @@ function compileFaceted(
 
     // Compute scales for this panel's area
     const panelScales = computeScales(panelSpecWithDomains, gridPanel.area, panelData);
-    applyColorScaleRange(panelScales, panelSpecWithDomains.encoding, theme);
+    applyColorScaleRange(panelScales, panelSpecWithDomains.encoding, theme, renderSpec.highlight);
     panelScales.defaultColor =
       chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
 

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

@@ -6,7 +6,13 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { clampStaggerDelay, resolveAnimation } from '../animation';
+import {
+  clampStaggerDelay,
+  ENTER_DEFAULTS,
+  EXIT_DEFAULTS,
+  resolveAnimation,
+  UPDATE_DEFAULTS,
+} from '../animation';
 
 // ---------------------------------------------------------------------------
 // resolveAnimation
@@ -21,14 +27,12 @@ describe('resolveAnimation', () => {
     expect(resolveAnimation(undefined)).toBeUndefined();
   });
 
-  it('returns defaults for true', () => {
+  it('returns all three phases with defaults for true', () => {
     const result = resolveAnimation(true);
     expect(result).toEqual({
-      enabled: true,
-      duration: 500,
-      ease: 'smooth',
-      staggerDelay: 80,
-      staggerOrder: 'index',
+      enter: { ...ENTER_DEFAULTS },
+      update: { ...UPDATE_DEFAULTS },
+      exit: { ...EXIT_DEFAULTS },
       annotationDelay: 200,
     });
   });
@@ -36,11 +40,9 @@ describe('resolveAnimation', () => {
   it('resolves AnimationConfig with enter: true', () => {
     const result = resolveAnimation({ enter: true });
     expect(result).toBeDefined();
-    expect(result!.enabled).toBe(true);
-    expect(result!.duration).toBe(500);
-    expect(result!.ease).toBe('smooth');
-    expect(result!.staggerDelay).toBe(80);
-    expect(result!.staggerOrder).toBe('index');
+    expect(result!.enter).toEqual(ENTER_DEFAULTS);
+    expect(result!.update).toEqual(UPDATE_DEFAULTS);
+    expect(result!.exit).toEqual(EXIT_DEFAULTS);
     expect(result!.annotationDelay).toBe(200);
   });
 
@@ -53,20 +55,41 @@ describe('resolveAnimation', () => {
       },
     });
     expect(result).toBeDefined();
-    expect(result!.duration).toBe(800);
-    expect(result!.ease).toBe('smooth');
-    expect(result!.staggerDelay).toBe(40);
-    expect(result!.staggerOrder).toBe('value');
+    expect(result!.enter).toEqual({
+      duration: 800,
+      ease: 'smooth',
+      staggerDelay: 40,
+      staggerOrder: 'value',
+    });
+    // Other phases still present with defaults
+    expect(result!.update).toEqual(UPDATE_DEFAULTS);
+    expect(result!.exit).toEqual(EXIT_DEFAULTS);
   });
 
-  it('returns undefined when enter is false', () => {
-    expect(resolveAnimation({ enter: false })).toBeUndefined();
+  it('enter: false, update: true produces update present, no enter', () => {
+    const result = resolveAnimation({ enter: false, update: true });
+    expect(result).toBeDefined();
+    expect(result!.enter).toBeUndefined();
+    expect(result!.update).toEqual(UPDATE_DEFAULTS);
+    expect(result!.exit).toEqual(EXIT_DEFAULTS);
+  });
+
+  it('update: false produces enter + exit present, update absent', () => {
+    const result = resolveAnimation({ update: false });
+    expect(result).toBeDefined();
+    expect(result!.enter).toEqual(ENTER_DEFAULTS);
+    expect(result!.update).toBeUndefined();
+    expect(result!.exit).toEqual(EXIT_DEFAULTS);
+  });
+
+  it('all phases false returns undefined', () => {
+    expect(resolveAnimation({ enter: false, update: false, exit: false })).toBeUndefined();
   });
 
   it('resolves stagger: false to staggerDelay: 0', () => {
     const result = resolveAnimation({ enter: { stagger: false } });
     expect(result).toBeDefined();
-    expect(result!.staggerDelay).toBe(0);
+    expect(result!.enter!.staggerDelay).toBe(0);
   });
 
   it('uses custom annotationDelay', () => {
@@ -75,15 +98,48 @@ describe('resolveAnimation', () => {
     expect(result!.annotationDelay).toBe(500);
   });
 
-  it('returns undefined when no phase is specified', () => {
-    // Empty config with no enter/update/exit should not produce animation
-    expect(resolveAnimation({})).toBeUndefined();
+  it('empty config resolves all phases with defaults (behaves like true)', () => {
+    const result = resolveAnimation({});
+    expect(result).toBeDefined();
+    expect(result!.enter).toEqual(ENTER_DEFAULTS);
+    expect(result!.update).toEqual(UPDATE_DEFAULTS);
+    expect(result!.exit).toEqual(EXIT_DEFAULTS);
   });
 
   it('preserves default annotationDelay when not overridden', () => {
     const result = resolveAnimation({ enter: { duration: 1000 } });
     expect(result!.annotationDelay).toBe(200);
   });
+
+  it('enter phase uses ENTER_DEFAULTS for unspecified fields', () => {
+    const result = resolveAnimation({ enter: { duration: 1000 } });
+    expect(result!.enter).toEqual({
+      duration: 1000,
+      ease: 'smooth',
+      staggerDelay: 80,
+      staggerOrder: 'index',
+    });
+  });
+
+  it('update phase uses UPDATE_DEFAULTS (no stagger by default)', () => {
+    const result = resolveAnimation(true);
+    expect(result!.update).toEqual({
+      duration: 500,
+      ease: 'smooth',
+      staggerDelay: 0,
+      staggerOrder: 'index',
+    });
+  });
+
+  it('exit phase uses EXIT_DEFAULTS (shorter duration)', () => {
+    const result = resolveAnimation(true);
+    expect(result!.exit).toEqual({
+      duration: 300,
+      ease: 'smooth',
+      staggerDelay: 0,
+      staggerOrder: 'index',
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,89 @@
+/**
+ * Tests for mark key utilities: serializeKeyValue() and dedupeKeys().
+ */
+
+import { describe, expect, it } from 'vitest';
+import { dedupeKeys, serializeKeyValue } from '../keys';
+
+// ---------------------------------------------------------------------------
+// serializeKeyValue
+// ---------------------------------------------------------------------------
+
+describe('serializeKeyValue', () => {
+  it('serializes strings as-is', () => {
+    expect(serializeKeyValue('hello')).toBe('hello');
+    expect(serializeKeyValue('')).toBe('');
+  });
+
+  it('serializes numbers to string', () => {
+    expect(serializeKeyValue(42)).toBe('42');
+    expect(serializeKeyValue(0)).toBe('0');
+    expect(serializeKeyValue(-3.14)).toBe('-3.14');
+  });
+
+  it('serializes booleans to string', () => {
+    expect(serializeKeyValue(true)).toBe('true');
+    expect(serializeKeyValue(false)).toBe('false');
+  });
+
+  it('serializes null to sentinel', () => {
+    expect(serializeKeyValue(null)).toBe('∅');
+  });
+
+  it('serializes undefined to sentinel', () => {
+    expect(serializeKeyValue(undefined)).toBe('∅');
+  });
+
+  it('serializes Date to epoch ms (not locale string)', () => {
+    const d = new Date('2024-01-15T00:00:00Z');
+    const result = serializeKeyValue(d);
+    expect(result).toBe(String(d.getTime()));
+    // Confirm it's purely numeric
+    expect(Number(result)).toBe(d.getTime());
+    // Confirm it does NOT use Date.toString
+    expect(result).not.toContain('Jan');
+    expect(result).not.toContain('Mon');
+  });
+
+  it('two Dates with same epoch produce same key', () => {
+    const d1 = new Date('2024-06-01T12:00:00Z');
+    const d2 = new Date(d1.getTime());
+    expect(serializeKeyValue(d1)).toBe(serializeKeyValue(d2));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dedupeKeys
+// ---------------------------------------------------------------------------
+
+describe('dedupeKeys', () => {
+  it('passes unique keys through unchanged', () => {
+    expect(dedupeKeys(['a', 'b', 'c'])).toEqual(['a', 'b', 'c']);
+  });
+
+  it('suffixes duplicates with occurrence index', () => {
+    expect(dedupeKeys(['a', 'a', 'a'])).toEqual(['a\x010', 'a\x011', 'a\x012']);
+  });
+
+  it('only suffixes keys that appear more than once', () => {
+    expect(dedupeKeys(['a', 'b', 'a'])).toEqual(['a\x010', 'b', 'a\x011']);
+  });
+
+  it('handles empty array', () => {
+    expect(dedupeKeys([])).toEqual([]);
+  });
+
+  it('handles single element', () => {
+    expect(dedupeKeys(['x'])).toEqual(['x']);
+  });
+
+  it('handles multiple duplicate groups', () => {
+    expect(dedupeKeys(['x', 'y', 'x', 'y', 'z'])).toEqual([
+      'x\x010',
+      'y\x010',
+      'x\x011',
+      'y\x011',
+      'z',
+    ]);
+  });
+});