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

package/registry/ui/area-chart.tsx

@@ -15,7 +15,7 @@ import { forwardRef, useMemo, type ForwardedRef, type ReactElement, type Ref } f
 import { ChartFrame } from "@squadbase/vantage/components"
 import { EChart } from "@squadbase/vantage/components"
 import type { ChartComparison, ChartForecast, NumericKeys } from "@squadbase/vantage/components"
-import { createContext, useCallback, useEffect, useRef, useState } from "react"
+import { createContext, useCallback, useEffect, useRef, useState, 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, ChartSeriesColor, ValueFormatter } from "@squadbase/vantage/components"
@@ -58,10 +58,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. */
@@ -117,8 +130,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"),
@@ -126,6 +141,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. */
@@ -133,6 +150,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 &&
@@ -158,7 +179,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.
@@ -173,8 +194,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) {
@@ -262,22 +286,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
 }
 
@@ -289,7 +314,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".
  */
@@ -300,12 +325,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(")) {
@@ -351,7 +377,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. */
@@ -365,9 +391,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(
@@ -381,7 +408,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)
@@ -390,7 +417,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) ---------- */
@@ -3557,9 +3584,8 @@ function AreaChartImpl<T extends Record<string, unknown>>(
   }: AreaChartProps<T>,
   ref: ForwardedRef<HTMLDivElement>,
 ) {
-  const tokens = useChartTokens()
   // Highlight labels are backed by the surface the chart sits on (a card, the page).
-  const { ref: frameRef, surface, width: plotWidth } = useChartSurface(ref, tokens)
+  const { ref: frameRef, surface, width: plotWidth, tokens } = useChartSurface(ref)
   // Ticks and on-plot labels read short (¥1億); the tooltip reads the value as `format` says.
   const tooltipFormatter = useMemo(() => resolveValueFormatter(valueFormatter, format), [valueFormatter, format])
   const axisFormatter = useMemo(() => resolveAxisFormatter(valueFormatter, format), [valueFormatter, format])

package/registry/ui/bar-chart.tsx

@@ -18,7 +18,7 @@ import { forwardRef, useMemo, type ForwardedRef, type ReactElement, type Ref } f
 import { ChartFrame } from "@squadbase/vantage/components"
 import { EChart } from "@squadbase/vantage/components"
 import type { ChartThreshold } from "@squadbase/vantage/components"
-import { createContext, useCallback, useEffect, useRef, useState } from "react"
+import { createContext, useCallback, useEffect, useRef, useState, 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, ChartSeriesColor, ValueFormatter } from "@squadbase/vantage/components"
@@ -61,10 +61,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. */
@@ -120,8 +133,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"),
@@ -129,6 +144,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. */
@@ -136,6 +153,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 &&
@@ -161,7 +182,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.
@@ -176,8 +197,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) {
@@ -265,22 +289,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
 }
 
@@ -292,7 +317,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".
  */
@@ -303,12 +328,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(")) {
@@ -354,7 +380,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. */
@@ -368,9 +394,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(
@@ -384,7 +411,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)
@@ -393,7 +420,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) ---------- */
@@ -3554,9 +3581,8 @@ function BarChartImpl<T extends Record<string, unknown>>(
   }: BarChartProps<T>,
   ref: ForwardedRef<HTMLDivElement>,
 ) {
-  const tokens = useChartTokens()
   // Highlight labels are backed by the surface the chart sits on (a card, the page).
-  const { ref: frameRef, surface, width: plotWidth } = useChartSurface(ref, tokens)
+  const { ref: frameRef, surface, width: plotWidth, tokens } = useChartSurface(ref)
   // Ticks and on-plot labels read short (¥1億); the tooltip reads the value as `format` says.
   const tooltipFormatter = useMemo(() => resolveValueFormatter(valueFormatter, format), [valueFormatter, format])
   const axisFormatter = useMemo(() => resolveAxisFormatter(valueFormatter, format), [valueFormatter, format])

package/registry/ui/bar-list.tsx

@@ -31,7 +31,7 @@ import { cn } from "@squadbase/vantage/ui"
 import { ChartFrame } from "@squadbase/vantage/components"
 import { toneForValue } from "@squadbase/vantage/components"
 import type { ChartColor, ChartCommonProps, ChartSeriesColor, ChartThreshold } 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 { ChartColors, ValueFormatter } from "@squadbase/vantage/components"
@@ -74,10 +74,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. */
@@ -133,8 +146,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"),
@@ -142,6 +157,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. */
@@ -149,6 +166,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 &&
@@ -174,7 +195,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.
@@ -189,8 +210,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) {
@@ -278,22 +302,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
 }
 
@@ -305,7 +330,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".
  */
@@ -316,12 +341,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(")) {
@@ -367,7 +393,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. */
@@ -381,9 +407,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(
@@ -397,7 +424,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)
@@ -406,7 +433,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) ---------- */