Stabilize accessors, add raster output for MCP

Author: emeeks

CLAUDE.md

@@ -467,5 +467,29 @@ import { CategoryColorProvider, LinkedCharts } from "semiotic"
 
 **`diagnoseConfig` catches common mistakes**: Run `diagnoseConfig("BarChart", props)` to check for empty data, bad dimensions, missing accessors, margin overflow, invisible bar padding, and more. Use `npx semiotic-ai --doctor` from CLI.
 
+## Performance
+
+**Prefer string accessors over function accessors**: `xAccessor="value"` is always referentially stable. `xAccessor={d => d.value}` creates a new function on every parent render, which can trigger unnecessary scene rebuilds. The pipeline stores use `.toString()` comparison to detect functionally identical inline arrow functions and skip re-resolution, but this heuristic doesn't work for closures that capture changing variables. When you must use a function accessor, memoize it with `useCallback` or define it outside the component:
+
+```jsx
+// Best: string accessor (always stable)
+<LineChart data={d} xAccessor="time" yAccessor="value" />
+
+// Good: function defined outside component (stable reference)
+const getX = (d) => d.timestamp.getTime()
+function MyChart() {
+  return <LineChart data={d} xAccessor={getX} yAccessor="value" />
+}
+
+// Acceptable: memoized function (stable across re-renders)
+function MyChart() {
+  const getX = useCallback((d) => d.timestamp.getTime(), [])
+  return <LineChart data={d} xAccessor={getX} yAccessor="value" />
+}
+
+// Avoid: inline arrow function (new reference every render)
+<LineChart data={d} xAccessor={d => d.timestamp.getTime()} yAccessor="value" />
+```
+
 ## Differentiators
 Network viz, geographic viz (choropleth, flow maps, distance cartograms), streaming canvas, realtime encoding, coordinated views, statistical summaries, AI hooks, chart serialization, CSS custom property theming (17 tokens), ThemeProvider + CSS-only theming, color-blind safe palettes, tooltip theming, annotation theming, keyboard navigation, interactive legends (highlight/isolate), direct labeling, gap handling, empty/loading states, landmark tick labels, LinkedCharts unified legend

ai/dist/mcp-server.js

@@ -315,6 +315,7 @@ async function renderChartHandler(args) {
     const component = args.component;
     const props = args.props ?? {};
     const theme = args.theme;
+    const format = args.format || "svg";
     if (!component) {
         return {
             content: [{ type: "text", text: `Missing 'component' field. Provide { component: '<name>', props: { ... } }. Available: ${componentNames.join(", ")}` }],
@@ -345,6 +346,31 @@ async function renderChartHandler(args) {
             svg = `<div style="${validVars}">${svg}</div>`;
         }
     }
+    // PNG rasterization via sharp (optional dependency)
+    if (format === "png") {
+        try {
+            // Dynamic import — sharp is an optional dependency
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const sharpMod = await Function('return import("sharp")')();
+            const sharpFn = sharpMod.default || sharpMod;
+            const pngBuffer = await sharpFn(Buffer.from(svg)).png().toBuffer();
+            const base64 = pngBuffer.toString("base64");
+            return {
+                content: [{ type: "text", text: `data:image/png;base64,${base64}` }],
+            };
+        }
+        catch (err) {
+            if (err.code === "MODULE_NOT_FOUND" || err.code === "ERR_MODULE_NOT_FOUND") {
+                return {
+                    content: [{ type: "text", text: `PNG output requires the 'sharp' package. Install it with: npm install sharp\n\nFalling back to SVG output:\n\n${svg}` }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: `PNG conversion failed: ${err.message}\n\nSVG output:\n\n${svg}` }],
+                isError: true,
+            };
+        }
+    }
     return {
         content: [{ type: "text", text: svg }],
     };
@@ -476,10 +502,11 @@ function createServer() {
         data: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())).min(1).max(5).describe("1-5 sample data objects"),
         intent: zod_1.z.enum(["comparison", "trend", "distribution", "relationship", "composition", "geographic", "network", "hierarchy"]).optional().describe("Visualization intent to narrow suggestions"),
     }, suggestChartHandler);
-    srv.tool("renderChart", `Render a Semiotic chart to static SVG. Returns SVG string or validation errors. Optionally pass theme CSS custom properties (--semiotic-bg, --semiotic-text, etc.) to style the output. Available components: ${componentNames.join(", ")}.`, {
+    srv.tool("renderChart", `Render a Semiotic chart to static SVG or PNG. Returns SVG string (default) or Base64-encoded PNG image. Optionally pass theme CSS custom properties (--semiotic-bg, --semiotic-text, etc.) to style the output. PNG requires the 'sharp' package to be installed. Available components: ${componentNames.join(", ")}.`, {
         component: zod_1.z.string().describe("Chart component name, e.g. 'LineChart', 'BarChart'"),
         props: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
         theme: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional().describe("CSS custom properties for theming, e.g. { '--semiotic-bg': '#1a1a2e', '--semiotic-text': '#ededed' }. Only --semiotic-* variables are applied."),
+        format: zod_1.z.enum(["svg", "png"]).optional().describe("Output format: 'svg' (default) returns SVG markup, 'png' returns a Base64-encoded PNG image. PNG requires the 'sharp' package."),
     }, renderChartHandler);
     srv.tool("diagnoseConfig", "Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, color contrast issues, etc). Checks WCAG color contrast ratios and suggests COLOR_BLIND_SAFE_CATEGORICAL for accessibility. Returns a human-readable diagnostic report with actionable fixes.", {
         component: zod_1.z.string().describe("Chart component name, e.g. 'LineChart'"),

ai/mcp-server.ts

@@ -305,10 +305,11 @@ async function suggestChartHandler(args: { data?: any[]; intent?: string }): Pro
   }
 }
 
-async function renderChartHandler(args: { component?: string; props?: Record<string, any>; theme?: Record<string, string> }): Promise<ToolResult> {
+async function renderChartHandler(args: { component?: string; props?: Record<string, any>; theme?: Record<string, string>; format?: string }): Promise<ToolResult> {
   const component = args.component
   const props: Record<string, any> = args.props ?? {}
   const theme = args.theme
+  const format = args.format || "svg"
 
   if (!component) {
     return {
@@ -345,6 +346,31 @@ async function renderChartHandler(args: { component?: string; props?: Record<str
     }
   }
 
+  // PNG rasterization via sharp (optional dependency)
+  if (format === "png") {
+    try {
+      // Dynamic import — sharp is an optional dependency
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const sharpMod = await (Function('return import("sharp")')() as Promise<any>)
+      const sharpFn = sharpMod.default || sharpMod
+      const pngBuffer: Buffer = await sharpFn(Buffer.from(svg)).png().toBuffer()
+      const base64 = pngBuffer.toString("base64")
+      return {
+        content: [{ type: "text" as const, text: `data:image/png;base64,${base64}` }],
+      }
+    } catch (err: any) {
+      if (err.code === "MODULE_NOT_FOUND" || err.code === "ERR_MODULE_NOT_FOUND") {
+        return {
+          content: [{ type: "text" as const, text: `PNG output requires the 'sharp' package. Install it with: npm install sharp\n\nFalling back to SVG output:\n\n${svg}` }],
+        }
+      }
+      return {
+        content: [{ type: "text" as const, text: `PNG conversion failed: ${err.message}\n\nSVG output:\n\n${svg}` }],
+        isError: true,
+      }
+    }
+  }
+
   return {
     content: [{ type: "text" as const, text: svg }],
   }
@@ -506,11 +532,12 @@ function createServer(): McpServer {
 
   srv.tool(
     "renderChart",
-    `Render a Semiotic chart to static SVG. Returns SVG string or validation errors. Optionally pass theme CSS custom properties (--semiotic-bg, --semiotic-text, etc.) to style the output. Available components: ${componentNames.join(", ")}.`,
+    `Render a Semiotic chart to static SVG or PNG. Returns SVG string (default) or Base64-encoded PNG image. Optionally pass theme CSS custom properties (--semiotic-bg, --semiotic-text, etc.) to style the output. PNG requires the 'sharp' package to be installed. Available components: ${componentNames.join(", ")}.`,
     {
       component: z.string().describe("Chart component name, e.g. 'LineChart', 'BarChart'"),
       props: z.record(z.string(), z.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
       theme: z.record(z.string(), z.string()).optional().describe("CSS custom properties for theming, e.g. { '--semiotic-bg': '#1a1a2e', '--semiotic-text': '#ededed' }. Only --semiotic-* variables are applied."),
+      format: z.enum(["svg", "png"]).optional().describe("Output format: 'svg' (default) returns SVG markup, 'png' returns a Base64-encoded PNG image. PNG requires the 'sharp' package."),
     },
     renderChartHandler
   )

package.json

@@ -248,6 +248,9 @@
     "react": "^18.1.0 || ^19.0.0",
     "react-dom": "^18.1.0 || ^19.0.0"
   },
+  "optionalDependencies": {
+    "sharp": ">=0.33.0"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/d3-quadtree": "^3.0.6",

src/components/charts/shared/diagnoseConfig.ts

@@ -472,6 +472,35 @@ function checkMarginOverflow(
   }
 }
 
+const ACCESSOR_PROPS = [
+  "xAccessor", "yAccessor", "timeAccessor", "valueAccessor",
+  "categoryAccessor", "colorBy", "sizeBy", "lineBy", "areaBy",
+  "stackBy", "groupBy", "orderAccessor", "y0Accessor",
+  "sourceAccessor", "targetAccessor", "nodeIDAccessor",
+  "childrenAccessor", "valueAccessor", "costAccessor",
+]
+
+function checkFunctionAccessors(
+  _component: string,
+  props: Record<string, any>,
+  out: Diagnosis[]
+): void {
+  const fnAccessors: string[] = []
+  for (const prop of ACCESSOR_PROPS) {
+    if (typeof props[prop] === "function") {
+      fnAccessors.push(prop)
+    }
+  }
+  if (fnAccessors.length > 0) {
+    out.push({
+      severity: "warning",
+      code: "FUNCTION_ACCESSOR",
+      message: `Function accessor${fnAccessors.length > 1 ? "s" : ""} detected: ${fnAccessors.join(", ")}. If defined inline (e.g. \`xAccessor={d => d.value}\`), every parent re-render creates a new reference which may trigger unnecessary scene rebuilds.`,
+      fix: `Use string accessors when possible (e.g. xAccessor="value"), or memoize with useCallback / define outside the component.`,
+    })
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -521,6 +550,7 @@ export function diagnoseConfig(
   checkLegendMarginTight(componentName, props, diagnoses)
   checkHeatmapStringAccessor(componentName, props, diagnoses)
   checkColorContrast(componentName, props, diagnoses)
+  checkFunctionAccessors(componentName, props, diagnoses)
 
   return {
     ok: diagnoses.every(d => d.severity === "warning"),

src/components/stream/OrdinalPipelineStore.ts

@@ -12,7 +12,7 @@ import type {
 import type { Changeset, Style, DecayConfig } from "./types"
 import { computeEasing, computeRawProgress, lerp, now as getTimestamp } from "./pipelineTransitionUtils"
 import type { ActiveTransition } from "./pipelineTransitionUtils"
-import { resolveAccessor, resolveStringAccessor } from "./accessorUtils"
+import { resolveAccessor, resolveStringAccessor, accessorsEquivalent } from "./accessorUtils"
 import { STREAMING_PALETTE } from "../charts/shared/colorUtils"
 import { buildBarScene, buildClusterBarScene } from "./ordinalSceneBuilders/barScene"
 import { buildPointScene, buildSwarmScene } from "./ordinalSceneBuilders/pointScene"
@@ -1000,10 +1000,54 @@ export class OrdinalPipelineStore {
   }
 
   updateConfig(config: Partial<OrdinalPipelineConfig>): void {
+    const prev = this.config
+
     if (config.colorScheme !== this.config.colorScheme) {
       this._colorSchemeMap = null
       this._colorSchemeIndex = 0
     }
+
     Object.assign(this.config, config)
+
+    // Re-resolve accessors only when the accessor source actually changed.
+    // Uses .toString() comparison to skip re-resolution for inline arrow functions
+    // that are recreated on every parent render but have identical source code.
+    if (config.oAccessor !== undefined || config.categoryAccessor !== undefined) {
+      const newO = config.oAccessor || config.categoryAccessor
+      const prevO = prev.oAccessor || prev.categoryAccessor
+      if (!accessorsEquivalent(newO, prevO)) {
+        this.getO = resolveStringAccessor(
+          this.config.oAccessor || this.config.categoryAccessor,
+          "category"
+        ) as (d: any) => string
+      }
+    }
+    if (config.rAccessor !== undefined) {
+      if (!accessorsEquivalent(
+        Array.isArray(config.rAccessor) ? config.rAccessor[0] : config.rAccessor,
+        Array.isArray(prev.rAccessor) ? prev.rAccessor[0] : prev.rAccessor
+      )) {
+        const rawR = this.config.rAccessor
+        if (Array.isArray(rawR)) {
+          this.rAccessors = rawR.map(acc => resolveAccessor(acc, "value"))
+          this.getR = this.rAccessors[0]
+        } else {
+          this.getR = resolveAccessor(rawR, "value")
+          this.rAccessors = [this.getR]
+        }
+      }
+    }
+    if (config.stackBy !== undefined && !accessorsEquivalent(config.stackBy, prev.stackBy)) {
+      this.getStack = resolveStringAccessor(this.config.stackBy)
+    }
+    if (config.groupBy !== undefined && !accessorsEquivalent(config.groupBy, prev.groupBy)) {
+      this.getGroup = resolveStringAccessor(this.config.groupBy)
+    }
+    if (config.colorAccessor !== undefined && !accessorsEquivalent(config.colorAccessor, prev.colorAccessor)) {
+      this.getColor = resolveStringAccessor(this.config.colorAccessor)
+    }
+    if (config.connectorAccessor !== undefined && !accessorsEquivalent(config.connectorAccessor, prev.connectorAccessor)) {
+      this.getConnector = resolveStringAccessor(this.config.connectorAccessor)
+    }
   }
 }

src/components/stream/PipelineStore.ts

@@ -35,7 +35,7 @@ import {
   buildRectNode,
   buildHeatcellNode
 } from "./SceneGraph"
-import { resolveAccessor, resolveRawAccessor, resolveStringAccessor } from "./accessorUtils"
+import { resolveAccessor, resolveRawAccessor, resolveStringAccessor, accessorsEquivalent } from "./accessorUtils"
 import { STREAMING_PALETTE } from "../charts/shared/colorUtils"
 import { computeEasing, computeRawProgress, lerp, now as getTimestamp } from "./pipelineTransitionUtils"
 import type { ActiveTransition } from "./pipelineTransitionUtils"
@@ -2140,6 +2140,8 @@ export class PipelineStore {
   }
 
   updateConfig(config: Partial<PipelineConfig>): void {
+    const prev = this.config
+
     // Invalidate color map caches when relevant config changes
     if (config.colorScheme !== undefined) {
       this._colorMapCache = null
@@ -2156,44 +2158,65 @@ export class PipelineStore {
       this._stackExtentCache = null
     }
 
+    // Track whether any accessor actually changed (not just new function identity)
+    let accessorChanged = false
+
     Object.assign(this.config, config)
 
-    // Re-resolve accessor functions when accessor config changes
+    // Re-resolve accessor functions only when the accessor source actually changed.
+    // Uses .toString() comparison to detect inline arrow functions that are
+    // recreated on every parent render but have identical source code.
     if (config.xAccessor !== undefined || config.yAccessor !== undefined
       || config.timeAccessor !== undefined || config.valueAccessor !== undefined) {
-      const isStreamingType = ["bar", "swarm", "waterfall"].includes(this.config.chartType)
-      const useStreamingDefaults = isStreamingType || this.config.runtimeMode === "streaming"
-      if (useStreamingDefaults) {
-        this.getX = resolveAccessor(this.config.timeAccessor || this.config.xAccessor, "time")
-        this.getY = resolveAccessor(this.config.valueAccessor || this.config.yAccessor, "value")
-      } else {
-        this.getX = resolveAccessor(this.config.xAccessor, "x")
-        this.getY = resolveAccessor(this.config.yAccessor, "y")
+      const xChanged = !accessorsEquivalent(config.xAccessor ?? config.timeAccessor, prev.xAccessor ?? prev.timeAccessor)
+      const yChanged = !accessorsEquivalent(config.yAccessor ?? config.valueAccessor, prev.yAccessor ?? prev.valueAccessor)
+      if (xChanged || yChanged) {
+        const isStreamingType = ["bar", "swarm", "waterfall"].includes(this.config.chartType)
+        const useStreamingDefaults = isStreamingType || this.config.runtimeMode === "streaming"
+        if (useStreamingDefaults) {
+          this.getX = resolveAccessor(this.config.timeAccessor || this.config.xAccessor, "time")
+          this.getY = resolveAccessor(this.config.valueAccessor || this.config.yAccessor, "value")
+        } else {
+          this.getX = resolveAccessor(this.config.xAccessor, "x")
+          this.getY = resolveAccessor(this.config.yAccessor, "y")
+        }
+        accessorChanged = true
       }
     }
-    if (config.groupAccessor !== undefined) {
+    if (config.groupAccessor !== undefined && !accessorsEquivalent(config.groupAccessor, prev.groupAccessor)) {
       this.getGroup = resolveStringAccessor(this.config.groupAccessor)
+      accessorChanged = true
     }
-    if (config.categoryAccessor !== undefined) {
+    if (config.categoryAccessor !== undefined && !accessorsEquivalent(config.categoryAccessor, prev.categoryAccessor)) {
       this.getCategory = resolveStringAccessor(this.config.categoryAccessor)
+      accessorChanged = true
     }
-    if (config.sizeAccessor !== undefined) {
+    if (config.sizeAccessor !== undefined && !accessorsEquivalent(config.sizeAccessor, prev.sizeAccessor)) {
       this.getSize = this.config.sizeAccessor
         ? resolveAccessor(this.config.sizeAccessor, "size")
         : undefined
+      accessorChanged = true
     }
-    if (config.colorAccessor !== undefined) {
+    if (config.colorAccessor !== undefined && !accessorsEquivalent(config.colorAccessor, prev.colorAccessor)) {
       this.getColor = resolveStringAccessor(this.config.colorAccessor)
+      accessorChanged = true
     }
-    if (config.y0Accessor !== undefined) {
+    if (config.y0Accessor !== undefined && !accessorsEquivalent(config.y0Accessor, prev.y0Accessor)) {
       this.getY0 = this.config.y0Accessor
         ? resolveAccessor(this.config.y0Accessor, "y0")
         : undefined
+      accessorChanged = true
     }
-    if (config.pointIdAccessor !== undefined) {
+    if (config.pointIdAccessor !== undefined && !accessorsEquivalent(config.pointIdAccessor, prev.pointIdAccessor)) {
       this.getPointId = resolveStringAccessor(this.config.pointIdAccessor)
+      accessorChanged = true
     }
 
-    this.needsFullRebuild = true
+    // Only mark full rebuild needed if non-accessor config changed or accessors actually changed.
+    // This prevents unnecessary scene rebuilds from unstable function references.
+    const nonAccessorKeys = Object.keys(config).filter(k => !k.endsWith("Accessor") && k !== "timeAccessor" && k !== "valueAccessor")
+    if (accessorChanged || nonAccessorKeys.length > 0) {
+      this.needsFullRebuild = true
+    }
   }
 }