@squadbase/vantage 0.6.2-dev1.5aae04e → 0.6.2-dev1.72360fb

package/registry/ui/donut-chart.tsx

@@ -22,7 +22,7 @@ import { forwardRef, useEffect, useMemo, useState, type ForwardedRef, type React
 import { ChartFrame } from "@squadbase/vantage/components"
 import { EChart } from "@squadbase/vantage/components"
 import type { ChartCommonProps, ChartEventPayload, ChartSeriesColor } from "@squadbase/vantage/components"
-import { createContext, useCallback, useRef } from "react"
+import { createContext, useCallback, useRef, type RefObject } from "react"
 import type { ChartTone } from "@squadbase/vantage/components"
 import { DEFAULT_LOCALE, EMPTY_VALUE, formatValue, toValueFormatter, type ValueFormat } from "@squadbase/vantage/components"
 import type { ChartColor, ChartColors, ValueFormatter } from "@squadbase/vantage/components"
@@ -64,10 +64,23 @@ interface ChartTokens {
   border: string | null
   /** Tooltip surface. */
   popover: string | null
+  /** Semantic and surface dependencies used by typed chart options. Optional for hand-built tokens. */
+  colors?: Record<string, string>
+  /** Actual inherited painting surface (may change without a token changing). */
+  surface?: string | null
   /** Tooltip text. */
   popoverForeground: string | null
 }
 
+// Keep scope out of the public token shape. A resolved snapshot remembers where arbitrary
+// var(--token) expressions must be read, without retaining unmounted charts globally.
+const tokenScopes = new WeakMap<ChartTokens, Element>()
+const OPTION_COLOR_TOKENS = [
+  "--background", "--card", "--muted", "--primary", "--destructive",
+  ...["positive", "negative", "warning", "neutral", "info"].flatMap((tone) =>
+    ["", "-fill", "-subtle"].map((suffix) => `--${tone}${suffix}`)),
+]
+
 let normalizeContext: CanvasRenderingContext2D | null | undefined
 
 /** The forms `fillStyle` serializes legacy colours to, and zrender can parse. */
@@ -123,8 +136,10 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     const color = read(token)
     if (color) series.push(color)
   }
-  return {
+  const tokens: ChartTokens = {
     series,
+    colors: Object.fromEntries(OPTION_COLOR_TOKENS.map((name) => [name, styles.getPropertyValue(name).trim()])),
+    surface: readChartSurface(target),
     ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
     foreground: read("--foreground"),
     mutedForeground: read("--muted-foreground"),
@@ -132,6 +147,8 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     popover: read("--popover"),
     popoverForeground: read("--popover-foreground"),
   }
+  tokenScopes.set(tokens, target)
+  return tokens
 }
 
 /** Structural equality, so a theme toggle that changes nothing doesn't re-init. */
@@ -139,6 +156,10 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
   if (a === b) return true
   if (!a || !b) return false
   return (
+    tokenScopes.get(a) === tokenScopes.get(b) &&
+    a.surface === b.surface &&
+    Object.keys(a.colors ?? {}).length === Object.keys(b.colors ?? {}).length &&
+    Object.entries(a.colors ?? {}).every(([name, value]) => b.colors?.[name] === value) &&
     a.series.length === b.series.length &&
     a.series.every((color, i) => color === b.series[i]) &&
     a.fontFamily === b.fontFamily &&
@@ -164,7 +185,7 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
  *    attributes alone leaves the chart painted in the previous palette until a
  *    reload — the tokens in the DOM are new, the canvas is not.
  */
-function watchChartTokens(onChange: () => void): () => void {
+function watchChartTokens(onChange: () => void, scope?: Element | null): () => void {
   if (typeof document === "undefined") return () => {}
   // Style edits arrive as bursts of mutations; coalesce them into one read, and
   // take it after the next frame so a swapped stylesheet has been applied.
@@ -179,8 +200,11 @@ function watchChartTokens(onChange: () => void): () => void {
 
   const themeObserver = new MutationObserver(schedule)
   const attributeFilter = ["class", "style", "data-theme"]
-  themeObserver.observe(document.documentElement, { attributes: true, attributeFilter })
-  if (document.body) themeObserver.observe(document.body, { attributes: true, attributeFilter })
+  // Only the chart and its ancestors can change its inherited theme. Never observe
+  // the document subtree: canvas/tooltip/rendering mutations would trigger every chart.
+  for (let node: Element | null = scope ?? document.body ?? document.documentElement; node; node = node.parentElement) {
+    themeObserver.observe(node, { attributes: true, attributeFilter })
+  }
 
   const styleObserver = new MutationObserver(schedule)
   if (document.head) {
@@ -268,22 +292,23 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
  * components that build an ECharts option from token colours themselves (the
  * typed charts), so their palette follows light/dark like `EChart`'s theme.
  */
-function useChartTokens(): ChartTokens | null {
+function useChartTokens(scope?: Element | null | RefObject<Element | null>): ChartTokens | null {
   const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
   // Compared here, not inside a `setTokens` updater: an updater that reads the DOM is
   // replayed by React on every rebase and returns a fresh object each time, so the state
   // never settles ("Maximum update depth exceeded" once the tokens change after mount).
   const tokensRef = useRef(tokens)
   useEffect(() => {
+    const target = scope && "current" in scope ? scope.current : scope
     const sync = () => {
-      const next = readChartTokens()
+      const next = readChartTokens(target)
       if (sameChartTokens(tokensRef.current, next)) return
       tokensRef.current = next
       setTokens(next)
     }
     sync()
-    return watchChartTokens(sync)
-  }, [])
+    return watchChartTokens(sync, target)
+  }, [scope])
   return tokens
 }
 
@@ -295,7 +320,7 @@ const EMBEDDED_VAR_RE = /var\(\s*(--[\w-]+)\s*\)/g
 /**
  * Turn chart colours into canvas-safe strings. `"chart-1"`〜`"chart-5"` come from
  * the resolved series tokens; `"positive"` / `"warning"` / `"negative"` / `"neutral"` (and the area
- * variants `"positive-fill"`, …) are read off the document root (`--positive`, …); `var(--token)` is read off the document root; any
+ * variants `"positive-fill"`, …) are read in the snapshot's inherited scope (`--positive`, …); `var(--token)` uses the same scope; any
  * other CSS colour is normalized like the tokens are. A colour that can't be
  * resolved comes back as `""`, which ECharts treats as "use the palette".
  */
@@ -306,12 +331,13 @@ function resolveChartColors(colors: readonly string[], tokens: ChartTokens | nul
     // Meaning colours are the theme tokens of the same name: same path as `var(--positive)`.
     if (TONE_NAME_RE.test(color.trim())) {
       if (typeof document === "undefined") return ""
-      return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue(`--${color.trim()}`)) ?? ""
+      const target = (tokens && tokenScopes.get(tokens)) ?? document.documentElement
+      return toCanvasColor(getComputedStyle(target).getPropertyValue(`--${color.trim()}`)) ?? ""
     }
     if (typeof document === "undefined") return color
     let value = color.trim()
     const cssVar = CSS_VAR_RE.exec(value)
-    const styles = getComputedStyle(document.documentElement)
+    const styles = getComputedStyle((tokens && tokenScopes.get(tokens)) ?? document.documentElement)
     if (cssVar) {
       value = styles.getPropertyValue(cssVar[1]!).trim() || (cssVar[2] ?? "").trim()
     } else if (value.includes("var(")) {
@@ -357,7 +383,7 @@ function readChartSurface(el: Element | null): string | null {
       if (color) return color
     }
   }
-  return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue("--background"))
+  return toCanvasColor(getComputedStyle(el ?? document.documentElement).getPropertyValue("--background"))
 }
 
 /** Widths are bucketed so a resize only rebuilds the option when the label budget can change. */
@@ -371,9 +397,10 @@ const WIDTH_BUCKET = 40
  */
 function useChartSurface<E extends Element>(
   forwarded: ForwardedRef<E>,
-  tokens: ChartTokens | null,
-): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined } {
+  tokens?: ChartTokens | null,
+): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined; tokens: ChartTokens | null } {
   const [node, setNode] = useState<E | null>(null)
+  const scopedTokens = useChartTokens(node)
   const [surface, setSurface] = useState<string | undefined>(undefined)
   const [width, setWidth] = useState<number | undefined>(undefined)
   const ref = useCallback(
@@ -387,7 +414,7 @@ function useChartSurface<E extends Element>(
   useEffect(() => {
     if (!node) return
     setSurface(readChartSurface(node) ?? undefined)
-  }, [node, tokens])
+  }, [node, tokens, scopedTokens])
   useEffect(() => {
     if (!node || typeof ResizeObserver === "undefined") return
     const update = (w: number) => setWidth(Math.floor(w / WIDTH_BUCKET) * WIDTH_BUCKET)
@@ -396,7 +423,7 @@ function useChartSurface<E extends Element>(
     observer.observe(node)
     return () => observer.disconnect()
   }, [node])
-  return { ref, surface, width }
+  return { ref, surface, width, tokens: scopedTokens }
 }
 
 /* ---------- inlined from @squadbase/squadkit registry/lib/chart-utils.ts (internal to @squadbase/vantage) ---------- */
@@ -3579,7 +3606,7 @@ function DonutChartImpl<T extends Record<string, unknown>>(
   const showLegend = donutOptions?.showLegend ?? true
   const valueFormatter = useMemo(() => resolveValueFormatter(valueFormatterProp, format), [valueFormatterProp, format])
 
-  const tokens = useChartTokens()
+  const { ref: frameRef, tokens } = useChartSurface(ref)
   const slices = useMemo(
     () => donutSlices(data, { index: labelKey, value: valueKey, colors, maxSlices, otherColor: CHART_OTHER_COLOR }),
     [data, labelKey, valueKey, colors, maxSlices],
@@ -3661,7 +3688,7 @@ function DonutChartImpl<T extends Record<string, unknown>>(
   return (
     <ChartFrame
       {...chartRootProps(rest)}
-      ref={ref}
+      ref={frameRef}
       title={title}
       summary={resolvedSummary}
       isLoading={isLoading ?? loading ?? false}

package/registry/ui/echart.tsx

@@ -58,7 +58,7 @@ import { Check, Copy, Download } from "lucide-react"
 import { cn } from "@squadbase/vantage/ui"
 import { Button } from "@squadbase/vantage/ui"
 import type { ChartActionsOptions } from "@squadbase/vantage/components"
-import { createContext, type ForwardedRef } from "react"
+import { createContext, type ForwardedRef, type RefObject } from "react"
 import type { ChartTone } from "@squadbase/vantage/components"
 
 /* ---------- inlined from @squadbase/squadkit registry/lib/chart-theme.ts (internal to @squadbase/vantage) ---------- */
@@ -95,10 +95,23 @@ interface ChartTokens {
   border: string | null
   /** Tooltip surface. */
   popover: string | null
+  /** Semantic and surface dependencies used by typed chart options. Optional for hand-built tokens. */
+  colors?: Record<string, string>
+  /** Actual inherited painting surface (may change without a token changing). */
+  surface?: string | null
   /** Tooltip text. */
   popoverForeground: string | null
 }
 
+// Keep scope out of the public token shape. A resolved snapshot remembers where arbitrary
+// var(--token) expressions must be read, without retaining unmounted charts globally.
+const tokenScopes = new WeakMap<ChartTokens, Element>()
+const OPTION_COLOR_TOKENS = [
+  "--background", "--card", "--muted", "--primary", "--destructive",
+  ...["positive", "negative", "warning", "neutral", "info"].flatMap((tone) =>
+    ["", "-fill", "-subtle"].map((suffix) => `--${tone}${suffix}`)),
+]
+
 let normalizeContext: CanvasRenderingContext2D | null | undefined
 
 /** The forms `fillStyle` serializes legacy colours to, and zrender can parse. */
@@ -154,8 +167,10 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     const color = read(token)
     if (color) series.push(color)
   }
-  return {
+  const tokens: ChartTokens = {
     series,
+    colors: Object.fromEntries(OPTION_COLOR_TOKENS.map((name) => [name, styles.getPropertyValue(name).trim()])),
+    surface: readChartSurface(target),
     ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
     foreground: read("--foreground"),
     mutedForeground: read("--muted-foreground"),
@@ -163,6 +178,8 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     popover: read("--popover"),
     popoverForeground: read("--popover-foreground"),
   }
+  tokenScopes.set(tokens, target)
+  return tokens
 }
 
 /** Structural equality, so a theme toggle that changes nothing doesn't re-init. */
@@ -170,6 +187,10 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
   if (a === b) return true
   if (!a || !b) return false
   return (
+    tokenScopes.get(a) === tokenScopes.get(b) &&
+    a.surface === b.surface &&
+    Object.keys(a.colors ?? {}).length === Object.keys(b.colors ?? {}).length &&
+    Object.entries(a.colors ?? {}).every(([name, value]) => b.colors?.[name] === value) &&
     a.series.length === b.series.length &&
     a.series.every((color, i) => color === b.series[i]) &&
     a.fontFamily === b.fontFamily &&
@@ -195,7 +216,7 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
  *    attributes alone leaves the chart painted in the previous palette until a
  *    reload — the tokens in the DOM are new, the canvas is not.
  */
-function watchChartTokens(onChange: () => void): () => void {
+function watchChartTokens(onChange: () => void, scope?: Element | null): () => void {
   if (typeof document === "undefined") return () => {}
   // Style edits arrive as bursts of mutations; coalesce them into one read, and
   // take it after the next frame so a swapped stylesheet has been applied.
@@ -210,8 +231,11 @@ function watchChartTokens(onChange: () => void): () => void {
 
   const themeObserver = new MutationObserver(schedule)
   const attributeFilter = ["class", "style", "data-theme"]
-  themeObserver.observe(document.documentElement, { attributes: true, attributeFilter })
-  if (document.body) themeObserver.observe(document.body, { attributes: true, attributeFilter })
+  // Only the chart and its ancestors can change its inherited theme. Never observe
+  // the document subtree: canvas/tooltip/rendering mutations would trigger every chart.
+  for (let node: Element | null = scope ?? document.body ?? document.documentElement; node; node = node.parentElement) {
+    themeObserver.observe(node, { attributes: true, attributeFilter })
+  }
 
   const styleObserver = new MutationObserver(schedule)
   if (document.head) {
@@ -299,22 +323,23 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
  * components that build an ECharts option from token colours themselves (the
  * typed charts), so their palette follows light/dark like `EChart`'s theme.
  */
-function useChartTokens(): ChartTokens | null {
+function useChartTokens(scope?: Element | null | RefObject<Element | null>): ChartTokens | null {
   const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
   // Compared here, not inside a `setTokens` updater: an updater that reads the DOM is
   // replayed by React on every rebase and returns a fresh object each time, so the state
   // never settles ("Maximum update depth exceeded" once the tokens change after mount).
   const tokensRef = useRef(tokens)
   useEffect(() => {
+    const target = scope && "current" in scope ? scope.current : scope
     const sync = () => {
-      const next = readChartTokens()
+      const next = readChartTokens(target)
       if (sameChartTokens(tokensRef.current, next)) return
       tokensRef.current = next
       setTokens(next)
     }
     sync()
-    return watchChartTokens(sync)
-  }, [])
+    return watchChartTokens(sync, target)
+  }, [scope])
   return tokens
 }
 
@@ -326,7 +351,7 @@ const EMBEDDED_VAR_RE = /var\(\s*(--[\w-]+)\s*\)/g
 /**
  * Turn chart colours into canvas-safe strings. `"chart-1"`〜`"chart-5"` come from
  * the resolved series tokens; `"positive"` / `"warning"` / `"negative"` / `"neutral"` (and the area
- * variants `"positive-fill"`, …) are read off the document root (`--positive`, …); `var(--token)` is read off the document root; any
+ * variants `"positive-fill"`, …) are read in the snapshot's inherited scope (`--positive`, …); `var(--token)` uses the same scope; any
  * other CSS colour is normalized like the tokens are. A colour that can't be
  * resolved comes back as `""`, which ECharts treats as "use the palette".
  */
@@ -337,12 +362,13 @@ function resolveChartColors(colors: readonly string[], tokens: ChartTokens | nul
     // Meaning colours are the theme tokens of the same name: same path as `var(--positive)`.
     if (TONE_NAME_RE.test(color.trim())) {
       if (typeof document === "undefined") return ""
-      return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue(`--${color.trim()}`)) ?? ""
+      const target = (tokens && tokenScopes.get(tokens)) ?? document.documentElement
+      return toCanvasColor(getComputedStyle(target).getPropertyValue(`--${color.trim()}`)) ?? ""
     }
     if (typeof document === "undefined") return color
     let value = color.trim()
     const cssVar = CSS_VAR_RE.exec(value)
-    const styles = getComputedStyle(document.documentElement)
+    const styles = getComputedStyle((tokens && tokenScopes.get(tokens)) ?? document.documentElement)
     if (cssVar) {
       value = styles.getPropertyValue(cssVar[1]!).trim() || (cssVar[2] ?? "").trim()
     } else if (value.includes("var(")) {
@@ -388,7 +414,7 @@ function readChartSurface(el: Element | null): string | null {
       if (color) return color
     }
   }
-  return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue("--background"))
+  return toCanvasColor(getComputedStyle(el ?? document.documentElement).getPropertyValue("--background"))
 }
 
 /** Widths are bucketed so a resize only rebuilds the option when the label budget can change. */
@@ -402,9 +428,10 @@ const WIDTH_BUCKET = 40
  */
 function useChartSurface<E extends Element>(
   forwarded: ForwardedRef<E>,
-  tokens: ChartTokens | null,
-): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined } {
+  tokens?: ChartTokens | null,
+): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined; tokens: ChartTokens | null } {
   const [node, setNode] = useState<E | null>(null)
+  const scopedTokens = useChartTokens(node)
   const [surface, setSurface] = useState<string | undefined>(undefined)
   const [width, setWidth] = useState<number | undefined>(undefined)
   const ref = useCallback(
@@ -418,7 +445,7 @@ function useChartSurface<E extends Element>(
   useEffect(() => {
     if (!node) return
     setSurface(readChartSurface(node) ?? undefined)
-  }, [node, tokens])
+  }, [node, tokens, scopedTokens])
   useEffect(() => {
     if (!node || typeof ResizeObserver === "undefined") return
     const update = (w: number) => setWidth(Math.floor(w / WIDTH_BUCKET) * WIDTH_BUCKET)
@@ -427,7 +454,7 @@ function useChartSurface<E extends Element>(
     observer.observe(node)
     return () => observer.disconnect()
   }, [node])
-  return { ref, surface, width }
+  return { ref, surface, width, tokens: scopedTokens }
 }
 
 /* ---------- end of inlined code ---------- */
@@ -664,6 +691,116 @@ export function echartSetOptionOpts(prev: EChartsOption | null, next: EChartsOpt
   return { notMerge: false, replaceMerge: [...types], lazyUpdate: true }
 }
 
+/**
+ * Component types that get a generated `id` when the option has none, so replaceMerge can match them across updates.
+ * Not `dataset` / `graphic` / `tooltip`: they are rebuilt on every update (there is nothing to transition).
+ */
+const ID_TYPES = [
+  "title", "legend", "grid", "xAxis", "yAxis", "polar", "radiusAxis", "angleAxis", "radar",
+  "dataZoom", "visualMap", "geo", "singleAxis", "calendar",
+] as const
+
+/**
+ * What `withStableIds` remembers between updates: per generated id, the shape last applied and how many
+ * times it changed (the id's `~v<n>` suffix); per component type, the order of its ids.
+ */
+export interface StableIdState {
+  ids: Map<string, { shape: string; version: number }>
+  order: Map<string, string[]>
+}
+export const createStableIdState = (): StableIdState => ({ ids: new Map(), order: new Map() })
+
+/**
+ * Shape of a component: which keys it has, recursively (arrays only as "array", values not at all —
+ * except `type`). A merge keeps keys the new option dropped, so a changed shape must not be merged.
+ */
+function shapeOf(v: unknown): string {
+  if (Array.isArray(v)) return "[]"
+  if (!v || typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) return "."
+  const o = v as Record<string, unknown>
+  return `{${Object.keys(o)
+    .filter((k) => o[k] !== undefined)
+    .sort()
+    .map((k) => (k === "type" || k === "id" ? `${k}=${String(o[k])}` : `${k}:${shapeOf(o[k])}`))
+    .join(",")}}`
+}
+
+/**
+ * Gives every series (and the common components) an `id` it does not have yet —
+ * series: `series:<name ?? index>`, others `<type>:<index>` — so an update that
+ * only changes values is matched to the existing component and transitions
+ * instead of being rebuilt. If the component's shape changed since `state` last
+ * saw it (a key was removed or added, the type changed), the id gets a new
+ * `~v<n>` suffix so replaceMerge builds it from scratch: the result then always
+ * equals applying the option with `notMerge`. Explicit ids are kept; the input is not mutated.
+ */
+export function withStableIds(option: EChartsOption, state: StableIdState = createStableIdState()): EChartsOption {
+  const out: Record<string, unknown> = { ...(option as Record<string, unknown>) }
+  const taken = new Set<string>()
+  const list = (v: unknown): Record<string, unknown>[] | null =>
+    Array.isArray(v) ? (v as Record<string, unknown>[]) : v && typeof v === "object" ? [v as Record<string, unknown>] : null
+  const give = (key: string, pick: (c: Record<string, unknown>, i: number) => string) => {
+    const items = list(out[key])
+    if (!items) return
+    const used = new Set<string>(items.flatMap((c) => (c && c.id != null ? [String(c.id)] : [])))
+    const bases = items.map((c, i) => {
+      if (!c || typeof c !== "object" || c.id != null) return null
+      let base = pick(c, i)
+      for (let n = 2; used.has(base) || taken.has(`${key}\u0000${base}`); n++) base = `${pick(c, i)}#${n}`
+      used.add(base)
+      taken.add(`${key}\u0000${base}`)
+      return base
+    })
+    // A merge fills the empty slots a removal left and keeps the slot order of what exists, so after any
+    // change in which components there are (or their order) it would not match a fresh render: rebuild them all.
+    const prevOrder = state.order.get(key) ?? []
+    const cur = bases.filter((b): b is string => b !== null)
+    const inOrder = cur.length === prevOrder.length && cur.every((b, i) => b === prevOrder[i])
+    state.order.set(key, cur)
+    out[key] = items.map((c, i) => {
+      const base = bases[i]
+      if (base == null) return c
+      const shape = shapeOf(c)
+      const prev = state.ids.get(base)
+      const version = !prev ? 0 : prev.shape === shape && inOrder ? prev.version : prev.version + 1
+      state.ids.set(base, { shape, version })
+      return { ...c, id: version ? `${base}~v${version}` : base }
+    })
+  }
+  give("series", (c, i) => `series:${typeof c.name === "string" && c.name ? c.name : i}`)
+  for (const key of ID_TYPES) give(key, (_c, i) => `${key}:${i}`)
+  return out as EChartsOption
+}
+
+/** Copy of the plain objects / arrays of an option (functions, class instances, Dates stay shared), to compare against later in-place edits. */
+export function snapshotOption<T>(v: T): T {
+  if (Array.isArray(v)) return v.map(snapshotOption) as T
+  if (v && typeof v === "object") {
+    const proto = Object.getPrototypeOf(v)
+    if (proto === Object.prototype || proto === null) {
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, snapshotOption(x)])) as T
+    }
+  }
+  return v
+}
+
+/** Structural equality for option trees; functions and other non-plain objects compare by reference. */
+export function optionEquals(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  if (Array.isArray(a)) {
+    const bb = b as unknown[]
+    return a.length === bb.length && a.every((v, i) => optionEquals(v, bb[i]))
+  }
+  if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime()
+  const pa = Object.getPrototypeOf(a)
+  if ((pa !== Object.prototype && pa !== null) || Object.getPrototypeOf(b) !== pa) return false
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && optionEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+}
+
 /** `graphic` text doesn't inherit the global `textStyle`, so give it the inherited font unless it sets its own. */
 function withGraphicFont(option: EChartsOption, fontFamily: string | undefined): EChartsOption {
   const graphic = (option as { graphic?: unknown }).graphic
@@ -717,42 +854,13 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   const containerRef = useRef<HTMLDivElement | null>(null)
   const [instance, setInstance] = useState<ECharts | null>(null)
   const [copied, setCopied] = useState(false)
-  // 初回はレンダー前に読めるので、マウント直後の作り直しが起きない
-  const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
+  const tokens = useChartTokens(containerRef)
   const reducedMotion = usePrefersReducedMotion()
   // What the current instance last received, to pick the merge mode of the next update.
   const appliedRef = useRef<EChartsOption | null>(null)
-
-  // 明暗の切り替えとスタイルシートの差し替え(dev で styles.css を書き換えたときなど)を
-  // 拾ってトークンを読み直す ― 何を見張るかは `watchChartTokens` 側が持つ。値が変わら
-  // ないときは state を更新せず、再 init を防ぐ。比較は updater 関数の中ではなく ref で行う:
-  // DOM を読む updater は React に何度も再生され、そのたびに新しいオブジェクトを返して
-  // 再描画が止まらなくなる(変数を後から当てた直後に Maximum update depth exceeded)。
-  const tokensRef = useRef(tokens)
-  useEffect(() => {
-    if (theme !== undefined) return
-    // Colours come from the document root, but the font is whatever this container inherits: an app
-    // can set its own font on a wrapper, and the canvas text has to match the DOM around it.
-    const sync = () => {
-      const base = readChartTokens()
-      const font = containerRef.current ? getComputedStyle(containerRef.current).fontFamily : ""
-      const next = base && font ? { ...base, fontFamily: font } : base
-      if (sameChartTokens(tokensRef.current, next)) return
-      tokensRef.current = next
-      setTokens(next)
-    }
-    sync()
-    const stop = watchChartTokens(sync)
-    // A font set on a wrapper (class / inline style) isn't seen by the document-level watcher.
-    const ancestors = new MutationObserver(sync)
-    for (let node = containerRef.current?.parentElement; node; node = node.parentElement) {
-      ancestors.observe(node, { attributes: true, attributeFilter: ["class", "style"] })
-    }
-    return () => {
-      stop()
-      ancestors.disconnect()
-    }
-  }, [theme])
+  // The option (before ids) as it was when applied, deep-copied; and the shape history behind the generated ids.
+  const snapshotRef = useRef<EChartsOption | null>(null)
+  const idStateRef = useRef<StableIdState>(createStableIdState())
 
   const autoTheme = useMemo(() => (tokens ? buildChartTheme(tokens) : undefined), [tokens])
   const resolvedTheme = theme ?? autoTheme
@@ -764,6 +872,7 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     if (!container) return
     const inst = init(container, resolvedTheme, { renderer: "canvas" })
     appliedRef.current = null
+    snapshotRef.current = null
     // `data-rendering` stays on until the (animated) paint is done, so anything
     // capturing the page — printing a document — can wait for real pixels.
     container.dataset.rendering = ""
@@ -790,21 +899,29 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   }, [resolvedTheme])
 
   useEffect(() => {
-    if (!instance) return
+    if (!instance || instance.isDisposed()) return
+    const prepared = withGraphicFont(
+      withMotionPreference(option, reducedMotion),
+      theme === undefined ? tokens?.fontFamily : undefined,
+    )
+    // Same content as last time (a re-render that built an equal option): nothing to redraw.
+    // Compared with a snapshot, so an in-place edit of a nested array of the caller's option still counts as a change.
+    if (snapshotRef.current && optionEquals(snapshotRef.current, prepared)) return
     if (containerRef.current) containerRef.current.dataset.rendering = ""
-    const next = withGraphicFont(withMotionPreference(option, reducedMotion), theme === undefined ? tokens?.fontFamily : undefined)
+    const next = withStableIds(prepared, idStateRef.current)
     instance.setOption(next, echartSetOptionOpts(appliedRef.current, next))
     appliedRef.current = next
+    snapshotRef.current = snapshotOption(prepared)
   }, [instance, option, reducedMotion, theme, tokens?.fontFamily])
 
   useEffect(() => {
-    if (!instance) return
+    if (!instance || instance.isDisposed()) return
     if (loading) instance.showLoading()
     else instance.hideLoading()
   }, [instance, loading])
 
   useEffect(() => {
-    if (!instance || !onEvents) return
+    if (!instance || instance.isDisposed() || !onEvents) return
     const entries = Object.entries(onEvents)
     for (const [event, handler] of entries) {
       instance.on(event, handler as EChartsEventHandler)