@opendata-ai/openchart-vanilla 7.7.0 → 7.9.0

package/src/barlist-mount.ts

@@ -248,7 +248,7 @@ export function createBarList(
       }
     }
 
-    if (currentLayout.animation?.enabled) {
+    if (currentLayout.animation?.enter) {
       animationCleanup = setupAnimationCleanup(newSvg, () => {
         if (pendingResize && !destroyed) {
           pendingResize = false;

package/src/barlist-renderer.ts

@@ -134,7 +134,7 @@ function renderRows(
       rowGroup.setAttribute('aria-label', row.aria.label);
     }
 
-    if (animation?.enabled) {
+    if (animation?.enter) {
       rowGroup.setAttribute('data-animation-index', String(row.animationIndex));
       const style = (rowGroup as SVGElement & ElementCSSInlineStyle).style;
       style.setProperty('--oc-mark-index', String(row.animationIndex));
@@ -236,7 +236,7 @@ export function renderBarListSVG(
   opts?: { animate?: boolean },
 ): SVGSVGElement {
   const { width, height, rows, a11y, watermark, animation } = layout;
-  const animate = opts?.animate && animation?.enabled;
+  const animate = opts?.animate && !!animation?.enter;
 
   const svg = createSVGElement('svg') as SVGSVGElement;
   svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
@@ -251,8 +251,8 @@ export function renderBarListSVG(
   const classes = animate ? 'oc-barlist oc-animate' : 'oc-barlist';
   svg.setAttribute('class', classes);
 
-  if (animate && animation) {
-    svg.style.setProperty('--oc-animation-duration', `${animation.duration}ms`);
+  if (animate && animation?.enter) {
+    svg.style.setProperty('--oc-animation-duration', `${animation.enter.duration}ms`);
     svg.style.setProperty('--oc-animation-stagger', '40ms');
   }
 

package/src/index.ts

@@ -31,6 +31,8 @@ export { createGraph } from './graph-mount';
 export type { ChartInstance, ExportOptions, MountOptions, UpdateOptions } from './mount';
 // Main mount API
 export { createChart } from './mount';
+// Geometry helpers for mark path reconstruction
+export { rectPathWithCorners } from './renderers/marks';
 // Cell renderers
 export {
   renderBarCell,

package/src/mount.ts

@@ -59,6 +59,7 @@ import { renderChartSVG } from './svg-renderer';
 import { createTextEditOverlay } from './text-edit-overlay';
 import { stampThemeProperties } from './theme-tokens';
 import { createTooltipManager, type TooltipManager } from './tooltip';
+import { canTransition, type GeometrySnapshot, runTransition } from './transition';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -193,6 +194,10 @@ export function createChart<TData extends DataRow = DataRow>(
   let cleanupAnimations: (() => void) | null = null;
   let pendingResize = false;
 
+  // Data-update transition state
+  let transitionHandle: import('./transition').TransitionHandle | null = null;
+  let transitionSnapshot: GeometrySnapshot | null = null;
+
   // Set when webfonts have loaded and a recompile is owed to reflect final font
   // metrics. The next render() that actually recompiles flips
   // data-oc-fonts-state to 'ready' and clears this. Deferring the flip (rather
@@ -621,6 +626,12 @@ export function createChart<TData extends DataRow = DataRow>(
       return;
     }
 
+    // Cancel any in-progress data-update transition
+    if (transitionHandle) {
+      transitionHandle.cancel();
+      transitionHandle = null;
+    }
+
     // Cancel any in-progress entrance animations before tearing down
     if (cleanupAnimations) {
       cleanupAnimations();
@@ -665,7 +676,7 @@ export function createChart<TData extends DataRow = DataRow>(
     }
 
     currentLayout = compile();
-    const shouldAnimate = isFirstRender && !!currentLayout.animation?.enabled;
+    const shouldAnimate = isFirstRender && !!currentLayout.animation?.enter;
     const crosshair = !!currentLayout.crosshair;
     svgElement = renderChartSVG(currentLayout, container, {
       animate: shouldAnimate,
@@ -831,6 +842,19 @@ export function createChart<TData extends DataRow = DataRow>(
 
   function update(newSpec: ChartSpec | GraphSpec, updateOpts?: UpdateOptions): void {
     if (destroyed) return;
+
+    // Capture pre-update state for transition gating
+    const prevSpec = currentSpec;
+    const prevLayout = currentLayout;
+    const entranceWasRunning = cleanupAnimations != null;
+
+    // Snapshot in-flight transition geometry before render() cancels it.
+    // This enables retargeting: the next transition starts from the
+    // interrupted position instead of snapping to the previous final state.
+    if (transitionHandle?.running) {
+      transitionSnapshot = transitionHandle.snapshot();
+    }
+
     currentSpec = newSpec;
     // A new spec can change theme.fonts.family; rebuild the measurer so layout
     // measures the font compile will actually render with.
@@ -845,6 +869,38 @@ export function createChart<TData extends DataRow = DataRow>(
       selectedElement = updateOpts.selectedElement ?? null;
     }
     render();
+
+    // After render, check if we can run a smooth transition instead of the
+    // instant swap that render() already performed.
+    if (
+      svgElement &&
+      canTransition({
+        prevLayout,
+        nextLayout: currentLayout,
+        prevSpec,
+        nextSpec: newSpec,
+        isFirstRender: false,
+        entranceInFlight: entranceWasRunning,
+      })
+    ) {
+      // Consume snapshot (if any) for retargeting, then clear
+      const snapshot = transitionSnapshot;
+      transitionSnapshot = null;
+
+      transitionHandle = runTransition({
+        svg: svgElement as SVGSVGElement,
+        prevLayout,
+        nextLayout: currentLayout,
+        animation: currentLayout.animation!,
+        fromSnapshot: snapshot ?? undefined,
+        onComplete: () => {
+          transitionHandle = null;
+        },
+      });
+    } else {
+      // No transition started; clear any stale snapshot
+      transitionSnapshot = null;
+    }
   }
 
   function resize(): void {
@@ -913,6 +969,13 @@ export function createChart<TData extends DataRow = DataRow>(
     if (destroyed) return;
     destroyed = true;
 
+    // Cancel any in-progress data-update transition
+    if (transitionHandle) {
+      transitionHandle.cancel();
+      transitionHandle = null;
+    }
+    transitionSnapshot = null;
+
     if (cleanupAnimations) {
       cleanupAnimations();
       cleanupAnimations = null;

package/src/renderers/axes.ts

@@ -10,6 +10,7 @@ import {
   TICK_LABEL_OFFSET,
   textAscent,
 } from '@opendata-ai/openchart-core';
+import { serializeKeyValue } from '@opendata-ai/openchart-engine';
 import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
 
 function appendCompoundLabel(
@@ -68,10 +69,14 @@ function renderAxis(
   // was set to [chartArea.x, chartArea.x + chartArea.width] (and similarly for y).
   // Don't add area.x/area.y again or you'll double-offset everything.
   for (const tick of axis.ticks) {
+    // Stable key for data-update transitions
+    const tickKey = serializeKeyValue(tick.value);
+
     if (orientation === 'x') {
       // Label (no tick marks -- gridlines provide sufficient reference)
       const label = createSVGElement('text');
       label.setAttribute('class', 'oc-axis-tick');
+      label.setAttribute('data-tick-key', tickKey);
 
       if (axis.tickAngle && Math.abs(axis.tickAngle) > 10) {
         // Rotated labels: anchor at the rotation pivot point
@@ -107,6 +112,7 @@ function renderAxis(
       // edge, no gutter reserved. The gridline itself is the visual axis.
       const label = createSVGElement('text');
       label.setAttribute('class', 'oc-axis-tick oc-axis-tick-inline');
+      label.setAttribute('data-tick-key', tickKey);
       setAttrs(label, {
         x: area.x,
         y: tick.position - 6,
@@ -118,6 +124,7 @@ function renderAxis(
     } else {
       const label = createSVGElement('text');
       label.setAttribute('class', 'oc-axis-tick');
+      label.setAttribute('data-tick-key', tickKey);
       setAttrs(label, {
         x: isRight ? area.x + area.width + TICK_LABEL_OFFSET : area.x - TICK_LABEL_OFFSET,
         y: tick.position,
@@ -207,9 +214,20 @@ function renderAxis(
   // Gridlines (positions are also absolute from the scales)
   // Skip gridlines for right-side y-axis (left y-axis gridlines are sufficient)
   if (!isRight) {
+    // Build position -> tick value map for keying gridlines
+    const posToTickKey = new Map<number, string>();
+    for (const tick of axis.ticks) {
+      posToTickKey.set(tick.position, serializeKeyValue(tick.value));
+    }
+
     for (const gridline of axis.gridlines) {
       const gl = createSVGElement('line');
       gl.setAttribute('class', 'oc-gridline');
+      // Stamp data-tick-key for data-update transitions
+      const glKey = posToTickKey.get(gridline.position);
+      if (glKey) {
+        gl.setAttribute('data-tick-key', glKey);
+      }
       if (orientation === 'y') {
         setAttrs(gl, {
           x1: area.x,

package/src/renderers/marks.ts

@@ -58,10 +58,14 @@ export function resetMarkRenderState(): void {
  */
 function stampAnimationAttrs(
   el: SVGElement,
-  mark: { animationIndex?: number },
+  mark: { animationIndex?: number; key?: string },
   fallbackIndex: number,
 ): void {
-  if (!currentAnimation?.enabled) return;
+  // Stamp stable identity key for data-update transitions (always, not just enter)
+  if (mark.key) {
+    el.setAttribute('data-key', mark.key);
+  }
+  if (!currentAnimation?.enter) return;
   const idx = mark.animationIndex ?? fallbackIndex;
   el.setAttribute('data-animation-index', String(idx));
   (el as SVGElement & ElementCSSInlineStyle).style.setProperty('--oc-mark-index', String(idx));
@@ -185,7 +189,7 @@ function renderAreaMark(mark: AreaMark, index: number): SVGElement {
  * stack, right of a horizontal stack) should round so the seams between
  * adjacent segments stay flush.
  */
-function _rectPathWithCorners(
+export function rectPathWithCorners(
   mark: RectMark,
   sides: NonNullable<RectMark['cornerRadiusSides']>,
 ): string {
@@ -219,7 +223,7 @@ function renderRectMark(mark: RectMark, index: number): SVGElement {
   g.setAttribute('class', 'oc-mark oc-mark-rect');
   stampAnimationAttrs(g, mark, index);
   // Use engine-provided orientation for animation direction
-  if (currentAnimation?.enabled && mark.orient === 'horizontal') {
+  if (currentAnimation?.enter && mark.orient === 'horizontal') {
     g.setAttribute('data-orient', 'horizontal');
   }
 
@@ -232,7 +236,7 @@ function renderRectMark(mark: RectMark, index: number): SVGElement {
     !!sides && (!sides.tl || !sides.tr || !sides.br || !sides.bl) && !!mark.cornerRadius;
   const shapeEl = partialCorners ? createSVGElement('path') : createSVGElement('rect');
   if (partialCorners) {
-    shapeEl.setAttribute('d', _rectPathWithCorners(mark, sides));
+    shapeEl.setAttribute('d', rectPathWithCorners(mark, sides));
   } else {
     setAttrs(shapeEl, {
       x: mark.x,
@@ -407,6 +411,16 @@ registerMarkRenderer('textMark', renderTextMark as MarkRenderer<Mark>);
 registerMarkRenderer('rule', renderRuleMark as MarkRenderer<Mark>);
 registerMarkRenderer('tick', renderTickMark as MarkRenderer<Mark>);
 
+/**
+ * Render a single mark to an SVG element without appending it anywhere.
+ * Used by the transition module to create ghost elements for exiting marks.
+ */
+export function renderSingleMark(mark: Mark, index: number): SVGElement | undefined {
+  const renderer = markRenderers[mark.type];
+  if (!renderer) return undefined;
+  return renderer(mark, index);
+}
+
 /** Extract series name from a mark for legend toggle matching. */
 function getMarkSeries(mark: Mark): string | undefined {
   // Line and area marks have an explicit seriesKey
@@ -459,7 +473,7 @@ export function renderMarks(parent: SVGElement, layout: ChartLayout): SVGElement
 
     // For stacked segments, set stack position for sequential animation chaining.
     // stackPos is computed by the engine on RectMark during compilation.
-    if (currentAnimation?.enabled && mark.type === 'rect') {
+    if (currentAnimation?.enter && mark.type === 'rect') {
       const rect = mark as RectMark;
       if (rect.stackGroup && rect.stackPos !== undefined) {
         el.setAttribute('data-stack-pos', String(rect.stackPos));
@@ -503,7 +517,7 @@ export function renderMarks(parent: SVGElement, layout: ChartLayout): SVGElement
 
     // Stamp animation index so the CSS stagger delay works for overlay labels
     // (they're not children of a .oc-mark-rect group that carries --oc-mark-index).
-    if (currentAnimation?.enabled) {
+    if (currentAnimation?.enter) {
       const idx = rect.animationIndex ?? i;
       label.setAttribute('data-animation-index', String(idx));
       (label as SVGElement & ElementCSSInlineStyle).style.setProperty(

package/src/sankey-mount.ts

@@ -399,7 +399,7 @@ export function createSankey(
     currentLayout = compile();
 
     // Determine if we should animate
-    const shouldAnimate = isFirstRender && currentLayout.animation?.enabled;
+    const shouldAnimate = isFirstRender && !!currentLayout.animation?.enter;
     isFirstRender = false;
 
     // Render
@@ -547,7 +547,7 @@ export function createSankey(
     currentLayout = compile();
 
     // Determine if we should animate
-    const shouldAnimate = currentLayout.animation?.enabled;
+    const shouldAnimate = !!currentLayout.animation?.enter;
     isFirstRender = false;
 
     // Render

package/src/sankey-renderer.ts

@@ -77,7 +77,7 @@ function stampAnimationAttrs(
   fallbackIndex: number,
   animation?: ResolvedAnimation,
 ): void {
-  if (!animation?.enabled) return;
+  if (!animation?.enter) return;
   const idx = mark.animationIndex ?? fallbackIndex;
   el.setAttribute('data-animation-index', String(idx));
   (el as SVGElement & ElementCSSInlineStyle).style.setProperty('--oc-mark-index', String(idx));
@@ -560,18 +560,19 @@ export function renderSankeySVG(
   svg.setAttribute('aria-label', layout.a11y.altText);
 
   // Classes: oc-chart oc-sankey, plus oc-animate if animated
-  const animate = animation?.enabled;
+  const enterPhase = animation?.enter;
+  const animate = !!enterPhase;
   const classes = animate ? 'oc-chart oc-sankey oc-animate' : 'oc-chart oc-sankey';
   svg.setAttribute('class', classes);
 
-  // Set animation CSS custom properties when enabled
-  if (animation?.enabled) {
+  // Set animation CSS custom properties when the enter phase is enabled
+  if (enterPhase) {
     const totalMarks = layout.nodes.length + layout.links.length;
-    const stagger = clampStaggerDelay(animation.staggerDelay, totalMarks);
-    svg.style.setProperty('--oc-animation-duration', `${animation.duration}ms`);
+    const stagger = clampStaggerDelay(enterPhase.staggerDelay, totalMarks);
+    svg.style.setProperty('--oc-animation-duration', `${enterPhase.duration}ms`);
     svg.style.setProperty('--oc-animation-stagger', `${stagger}ms`);
-    svg.style.setProperty('--oc-annotation-delay', `${animation.annotationDelay}ms`);
-    const easeVar = EASE_VAR_MAP[animation.ease] || EASE_VAR_MAP.smooth;
+    svg.style.setProperty('--oc-annotation-delay', `${animation!.annotationDelay}ms`);
+    const easeVar = EASE_VAR_MAP[enterPhase.ease] || EASE_VAR_MAP.smooth;
     svg.style.setProperty('--oc-animation-ease', easeVar);
   }
 

package/src/static.ts

@@ -8,12 +8,14 @@ import type {
   LayerSpec,
   ResolvedTheme,
   ThemeConfig,
+  TileMapSpec,
 } from '@opendata-ai/openchart-core';
-import { adaptForLightLineStroke, isLayerSpec } from '@opendata-ai/openchart-core';
-import { compileChart, compileLayer } from '@opendata-ai/openchart-engine';
+import { adaptForLightLineStroke, isLayerSpec, isTileMapSpec } from '@opendata-ai/openchart-core';
+import { compileChart, compileLayer, compileTileMap } from '@opendata-ai/openchart-engine';
 import { SVG_NS } from './renderers/svg-dom';
 import { resetSvgIdCounter } from './svg-ids';
 import { renderChartSVG } from './svg-renderer';
+import { renderTileMapSVG } from './tilemap-renderer';
 
 const esmRequire = createRequire(import.meta.url);
 
@@ -142,7 +144,7 @@ function stripInteractiveElements(svg: Element): void {
  * as no code schedules microtasks that outlive the call.
  */
 export function renderStaticSVG(
-  spec: ChartSpec | LayerSpec,
+  spec: ChartSpec | LayerSpec | TileMapSpec,
   options?: StaticRenderOptions,
 ): string {
   if (rendering) {
@@ -174,37 +176,45 @@ export function renderStaticSVG(
       watermark: options?.watermark,
     };
 
-    let layout: ChartLayout;
-    if (isLayerSpec(spec)) {
-      layout = compileLayer(spec, compileOpts);
+    let svg: SVGElement;
+    let themeForStyle: ResolvedTheme;
+
+    if (isTileMapSpec(spec)) {
+      const tileMapLayout = compileTileMap(spec, compileOpts);
+      svg = renderTileMapSVG(tileMapLayout, { animate: false });
+      themeForStyle = tileMapLayout.theme;
     } else {
-      layout = compileChart(spec, compileOpts);
+      let layout: ChartLayout;
+      if (isLayerSpec(spec)) {
+        layout = compileLayer(spec, compileOpts);
+      } else {
+        layout = compileChart(spec, compileOpts);
+      }
+
+      const container = win.document.createElement('div');
+      Object.defineProperty(container, 'getBoundingClientRect', {
+        value: () => ({
+          width,
+          height,
+          top: 0,
+          left: 0,
+          right: width,
+          bottom: height,
+          x: 0,
+          y: 0,
+          toJSON: () => ({}),
+        }),
+      });
+
+      svg = renderChartSVG(layout, container as unknown as HTMLElement, {
+        animate: false,
+        crosshair: false,
+      });
+
+      stripInteractiveElements(svg);
+      themeForStyle = layout.theme;
     }
 
-    const container = win.document.createElement('div');
-    Object.defineProperty(container, 'getBoundingClientRect', {
-      value: () => ({
-        width,
-        height,
-        top: 0,
-        left: 0,
-        right: width,
-        bottom: height,
-        x: 0,
-        y: 0,
-        toJSON: () => ({}),
-      }),
-    });
-
-    // renderChartSVG appends to container; the container and SVG are owned by
-    // the happy-dom Window which is closed in the finally block.
-    const svg = renderChartSVG(layout, container as unknown as HTMLElement, {
-      animate: false,
-      crosshair: false,
-    });
-
-    stripInteractiveElements(svg);
-
     const doc = win.document as unknown as Document;
     let defs = svg.querySelector('defs');
     if (!defs) {
@@ -212,7 +222,7 @@ export function renderStaticSVG(
       svg.insertBefore(defs as unknown as Node, svg.firstChild);
     }
     const styleEl = doc.createElementNS(SVG_NS, 'style');
-    styleEl.textContent = buildThemeStyleBlock(layout.theme);
+    styleEl.textContent = buildThemeStyleBlock(themeForStyle);
     defs.insertBefore(styleEl as unknown as Node, defs.firstChild);
 
     const serializer = new (

package/src/svg-renderer.ts

@@ -82,14 +82,15 @@ export function renderChartSVG(
   const classes = opts?.animate ? 'oc-chart oc-animate' : 'oc-chart';
   svg.setAttribute('class', classes);
 
-  // Set animation CSS custom properties when enabled
-  if (animation?.enabled) {
+  // Set animation CSS custom properties when the enter phase is enabled
+  const enterPhase = animation?.enter;
+  if (enterPhase) {
     const markCount = layout.marks.length;
-    const stagger = clampStaggerDelay(animation.staggerDelay, markCount);
-    svg.style.setProperty('--oc-animation-duration', `${animation.duration}ms`);
+    const stagger = clampStaggerDelay(enterPhase.staggerDelay, markCount);
+    svg.style.setProperty('--oc-animation-duration', `${enterPhase.duration}ms`);
     svg.style.setProperty('--oc-animation-stagger', `${stagger}ms`);
-    svg.style.setProperty('--oc-annotation-delay', `${animation.annotationDelay}ms`);
-    const easeVar = EASE_VAR_MAP[animation.ease] || EASE_VAR_MAP.smooth;
+    svg.style.setProperty('--oc-annotation-delay', `${animation!.annotationDelay}ms`);
+    const easeVar = EASE_VAR_MAP[enterPhase.ease] || EASE_VAR_MAP.smooth;
     svg.style.setProperty('--oc-animation-ease', easeVar);
 
     // Compute per-segment duration for stacked bars so the total bar animation
@@ -105,7 +106,7 @@ export function renderChartSVG(
       }
     }
     if (maxSegments > 0) {
-      const segDuration = Math.round(animation.duration / maxSegments);
+      const segDuration = Math.round(enterPhase.duration / maxSegments);
       svg.style.setProperty('--oc-stack-segment-duration', `${segDuration}ms`);
     }
   }

package/src/table-mount.ts

@@ -246,7 +246,7 @@ export function createTable(
       }
 
       currentLayout = compile();
-      const shouldAnimate = isFirstRender && !!currentLayout.animation?.enabled;
+      const shouldAnimate = isFirstRender && !!currentLayout.animation?.enter;
       wrapperElement = renderTable(currentLayout, container, { animate: shouldAnimate });
 
       // Set up animation cleanup on first animated render

package/src/table-renderer.ts

@@ -417,14 +417,14 @@ export function renderTable(
 
   // Animation: stamp CSS custom properties and add oc-animate class BEFORE
   // DOM insertion to avoid a flash of final state.
-  if (opts?.animate && layout.animation?.enabled) {
-    const anim = layout.animation;
+  if (opts?.animate && layout.animation?.enter) {
+    const enterPhase = layout.animation.enter;
     const rowCount = layout.rows.length;
-    const stagger = clampStaggerDelay(anim.staggerDelay, rowCount);
+    const stagger = clampStaggerDelay(enterPhase.staggerDelay, rowCount);
     const s = wrapper.style;
-    s.setProperty('--oc-animation-duration', `${anim.duration}ms`);
+    s.setProperty('--oc-animation-duration', `${enterPhase.duration}ms`);
     s.setProperty('--oc-animation-stagger', `${stagger}ms`);
-    s.setProperty('--oc-animation-ease', EASE_VAR_MAP[anim.ease] || EASE_VAR_MAP.smooth);
+    s.setProperty('--oc-animation-ease', EASE_VAR_MAP[enterPhase.ease] || EASE_VAR_MAP.smooth);
     wrapper.classList.add('oc-animate');
   }
 

package/src/tilemap-mount.ts

@@ -287,7 +287,7 @@ export function createTileMap(
     }
 
     // Setup animation cleanup only when actually animating
-    if (animate && currentLayout.animation?.enabled) {
+    if (animate && currentLayout.animation?.enter) {
       animationCleanup = setupAnimationCleanup(newSvg, () => {
         // On animation complete, check if resize was pending
         if (pendingResize && !destroyed) {

package/src/tilemap-renderer.ts

@@ -13,6 +13,7 @@ import type {
 } from '@opendata-ai/openchart-core';
 import { textAscent } from '@opendata-ai/openchart-core';
 import { renderLegend } from './renderers/legend';
+import { nextSvgId } from './svg-ids';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
 const XLINK_NS = 'http://www.w3.org/1999/xlink';
@@ -23,8 +24,6 @@ const EASE_VAR_MAP: Record<string, string> = {
   snappy: 'var(--oc-ease-snappy)',
 };
 
-let gradientIdCounter = 0;
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -211,7 +210,7 @@ function renderTiles(
   // Base delay spreads tiles across ~800ms window, jitter adds +-40% variation
   // so some tiles pop in clusters while others have longer gaps.
   const tileDelays: number[] = [];
-  if (animation?.enabled) {
+  if (animation?.enter) {
     const baseStagger = 800 / Math.max(tiles.length, 1);
     let seed = 17;
     for (let i = 0; i < tiles.length; i++) {
@@ -232,7 +231,7 @@ function renderTiles(
       tileGroup.setAttribute('aria-label', tile.aria.label);
     }
 
-    if (animation?.enabled) {
+    if (animation?.enter) {
       const idx = tile.animationIndex ?? i;
       tileGroup.setAttribute('data-animation-index', String(idx));
       (tileGroup as SVGElement & ElementCSSInlineStyle).style.setProperty(
@@ -322,7 +321,7 @@ function renderGradientLegend(parent: SVGElement, layout: TileMapLayout): void {
     parent.insertBefore(defs, parent.firstChild);
   }
 
-  const gradientId = `oc-tilemap-legend-gradient-${gradientIdCounter++}`;
+  const gradientId = nextSvgId('oc-tilemap-legend-gradient');
   const grad = createSVGElement('linearGradient');
   grad.id = gradientId;
   grad.setAttribute('x1', '0%');
@@ -407,7 +406,7 @@ export function renderTileMapSVG(
   opts?: { animate?: boolean },
 ): SVGSVGElement {
   const { width, height, tiles, a11y, watermark, animation } = layout;
-  const animate = opts?.animate && animation?.enabled;
+  const animate = opts?.animate && !!animation?.enter;
 
   const svg = createSVGElement('svg') as SVGSVGElement;
   svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
@@ -419,13 +418,13 @@ export function renderTileMapSVG(
   const classes = animate ? 'oc-tilemap oc-animate' : 'oc-tilemap';
   svg.setAttribute('class', classes);
 
-  if (animate && animation) {
+  if (animate && animation?.enter) {
     // Target ~1s total: stagger window ~800ms + per-tile pop ~200ms
     const stagger = Math.max(5, Math.round(800 / Math.max(tiles.length, 1)));
-    svg.style.setProperty('--oc-animation-duration', `${animation.duration}ms`);
+    svg.style.setProperty('--oc-animation-duration', `${animation.enter.duration}ms`);
     svg.style.setProperty('--oc-animation-stagger', `${stagger}ms`);
     svg.style.setProperty('--oc-annotation-delay', `${animation.annotationDelay}ms`);
-    const easeVar = EASE_VAR_MAP[animation.ease] || EASE_VAR_MAP.smooth;
+    const easeVar = EASE_VAR_MAP[animation.enter.ease] || EASE_VAR_MAP.smooth;
     svg.style.setProperty('--oc-animation-ease', easeVar);
   }