refactor: address code review must-fix items for v7-cohesion-pt2

- Restore examples/src/animation.stories.tsx annotation block that was
  accidentally committed in 3b59d20 (the file had unstaged cleanup work
  predating this refactor).
- Wrap marks render in try/finally so resetMarkRenderState fires even if
  any downstream renderer throws. Previously the reset was pure theater
  without exception safety.
- Split the compile.ts ORCHESTRATION INVARIANTS block comment into three
  inline callouts co-located with the lines they guard, so a reader
  reordering the second half of compileChart sees the invariant at the
  point of mutation instead of 70 lines above.

Author: rileyhilliard

examples/src/animation.stories.tsx

@@ -498,14 +498,14 @@ const annotationDelaySpec: ChartSpec = {
     },
   },
   annotations: [
-    // {
-    //   type: 'text',
-    //   text: 'Product relaunch',
-    //   x: '2024-04',
-    //   y: 53,
-    //   offset: { dx: -80, dy: -18 },
-    //   connector: true,
-    // },
+    {
+      type: 'text',
+      text: 'Product relaunch',
+      x: '2024-04',
+      y: 53,
+      offset: { dx: -80, dy: -18 },
+      connector: true,
+    },
     {
       type: 'refline',
       y: 70,

packages/engine/src/compile.ts

@@ -309,11 +309,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     theme = adaptTheme(theme);
   }
 
-  // ORCHESTRATION INVARIANTS — do not reorder without care:
-  // 1. Legend is computed twice (preliminary + refined) to break a dims/legend dependency cycle.
-  // 2. computeGridlines mutates `axes` in place.
-  // 3. scales.defaultColor is set post-computeScales because the resolution needs theme context.
-
+  // INVARIANT 1 — double legend pass: preliminaryArea → computeDimensions → legendArea → final
+  // legend. Breaks a dims/legend dependency cycle. Do not collapse into one call.
   // Compute legend first (needs to reserve space)
   const preliminaryArea: Rect = {
     x: 0,
@@ -376,8 +373,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Update color scale to use theme palette (only when user hasn't provided an explicit range)
   applyColorScaleRange(scales, renderSpec.encoding, theme);
 
-  // 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.
+  // INVARIANT 3 — post-hoc defaultColor: must run AFTER computeScales since resolution needs
+  // theme context. Do not move into computeScales (would require threading theme through).
+  // If the user set a fill on the mark def, it takes priority over the theme's first categorical.
   scales.defaultColor = chartSpec.markDef.fill ?? theme.colors.categorical[0];
 
   // Arc charts (pie/donut) don't use axes or gridlines
@@ -388,7 +386,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     ? { x: undefined, y: undefined }
     : computeAxes(scales, chartArea, strategy, theme, options.measureText);
 
-  // Compute gridlines (stored in axes, used by adapters via axes.y.gridlines)
+  // INVARIANT 2 — computeGridlines mutates `axes` in place. Downstream consumers read
+  // axes.y.gridlines off the same object. Do not introduce a copy-on-write.
   if (!isRadial) {
     computeGridlines(axes, chartArea);
   }

packages/vanilla/src/svg-renderer.ts

@@ -131,55 +131,57 @@ export function renderChartSVG(
   svg.appendChild(defs);
 
   // Prime mark-renderer module-level state so mark sub-renderers can resolve
-  // animation + gradient fills without signature changes.
+  // animation + gradient fills without signature changes. try/finally guarantees
+  // the reset fires even if any downstream renderer throws, so the next render
+  // starts with a clean slate.
   setMarkRenderState({ animation, gradientMap });
+  try {
+    // Render layers in order (back to front)
+    // Axes render outside clip (labels extend beyond chart area)
+    renderAxes(svg, layout);
+
+    // Marks are clipped to chart area so area fills don't cover chrome
+    const clippedGroup = createSVGElement('g');
+    clippedGroup.setAttribute('clip-path', `url(#${clipId})`);
+    renderMarks(clippedGroup, layout);
+
+    // Add transparent overlay rect for line/area charts to enable voronoi tooltip lookup.
+    // Only added when there are line or area marks with dataPoints, and no explicit
+    // PointMark objects (which use per-element event handling instead).
+    const hasLineOrAreaWithDataPoints = layout.marks.some(
+      (m) => (m.type === 'line' || m.type === 'area') && m.dataPoints && m.dataPoints.length > 0,
+    );
+    const hasPointMarks = layout.marks.some((m) => m.type === 'point');
+    if (hasLineOrAreaWithDataPoints && !hasPointMarks) {
+      const overlay = createSVGElement('rect');
+      setAttrs(overlay, {
+        x: layout.area.x,
+        y: layout.area.y,
+        width: layout.area.width,
+        height: layout.area.height,
+        fill: 'transparent',
+      });
+      overlay.setAttribute('class', 'oc-voronoi-overlay');
+      overlay.setAttribute('data-voronoi-overlay', 'true');
+      clippedGroup.appendChild(overlay);
+    }
 
-  // Render layers in order (back to front)
-  // Axes render outside clip (labels extend beyond chart area)
-  renderAxes(svg, layout);
-
-  // Marks are clipped to chart area so area fills don't cover chrome
-  const clippedGroup = createSVGElement('g');
-  clippedGroup.setAttribute('clip-path', `url(#${clipId})`);
-  renderMarks(clippedGroup, layout);
-
-  // Add transparent overlay rect for line/area charts to enable voronoi tooltip lookup.
-  // Only added when there are line or area marks with dataPoints, and no explicit
-  // PointMark objects (which use per-element event handling instead).
-  const hasLineOrAreaWithDataPoints = layout.marks.some(
-    (m) => (m.type === 'line' || m.type === 'area') && m.dataPoints && m.dataPoints.length > 0,
-  );
-  const hasPointMarks = layout.marks.some((m) => m.type === 'point');
-  if (hasLineOrAreaWithDataPoints && !hasPointMarks) {
-    const overlay = createSVGElement('rect');
-    setAttrs(overlay, {
-      x: layout.area.x,
-      y: layout.area.y,
-      width: layout.area.width,
-      height: layout.area.height,
-      fill: 'transparent',
-    });
-    overlay.setAttribute('class', 'oc-voronoi-overlay');
-    overlay.setAttribute('data-voronoi-overlay', 'true');
-    clippedGroup.appendChild(overlay);
-  }
-
-  svg.appendChild(clippedGroup);
+    svg.appendChild(clippedGroup);
 
-  renderAnnotations(svg, layout);
-  renderLegend(svg, layout.legend);
+    renderAnnotations(svg, layout);
+    renderLegend(svg, layout.legend);
 
-  // Chrome renders on top so titles are never obscured by chart elements
-  renderChrome(svg, layout);
+    // Chrome renders on top so titles are never obscured by chart elements
+    renderChrome(svg, layout);
 
-  // Brand renders as a footer item, right-aligned on the source/footer row
-  if (layout.watermark) {
-    renderBrand(svg, layout);
+    // Brand renders as a footer item, right-aligned on the source/footer row
+    if (layout.watermark) {
+      renderBrand(svg, layout);
+    }
+  } finally {
+    resetMarkRenderState();
   }
 
-  // Reset module-level state after rendering
-  resetMarkRenderState();
-
   container.appendChild(svg);
   return svg;
 }