Improve tests & docs

Author: emeeks

docs/src/App.js

@@ -80,6 +80,7 @@ import ObservationHooksPage from "./pages/features/ObservationHooksPage"
 import SerializationPage from "./pages/features/SerializationPage"
 import VegaLiteTranslatorPage from "./pages/features/VegaLiteTranslatorPage"
 import StreamingSystemModelPage from "./pages/features/StreamingSystemModelPage"
+import PerformancePage from "./pages/features/PerformancePage"
 
 // New cookbook pages
 import CandlestickChartPage from "./pages/cookbook/CandlestickChartPage"
@@ -369,6 +370,7 @@ export default function DocsApp() {
               <Route path="serialization" element={<SerializationPage />} />
               <Route path="vega-lite" element={<VegaLiteTranslatorPage />} />
               <Route path="streaming-system-model" element={<StreamingSystemModelPage />} />
+              <Route path="performance" element={<PerformancePage />} />
             </Route>
 
             {/* Using Server-Side Rendering */}

docs/src/components/navData.js

@@ -107,7 +107,8 @@ const navData = [
       { title: "AI Observation Hooks", path: "/features/observation-hooks" },
       { title: "Serialization", path: "/features/serialization" },
       { title: "Vega-Lite Translator", path: "/features/vega-lite" },
-      { title: "Streaming System Model", path: "/features/streaming-system-model" }
+      { title: "Streaming System Model", path: "/features/streaming-system-model" },
+      { title: "Performance", path: "/features/performance" }
     ]
   },
   {

docs/src/pages/features/PerformancePage.js

@@ -0,0 +1,162 @@
+import React from "react"
+import CodeBlock from "../../components/CodeBlock"
+import PageLayout from "../../components/PageLayout"
+import { Link } from "react-router-dom"
+
+export default function PerformancePage() {
+  return (
+    <PageLayout title="Performance" subtitle="Accessor stability, memoization, and rendering efficiency">
+      <section>
+        <h2>Accessor Stability</h2>
+        <p>
+          Semiotic's canvas-based rendering pipeline rebuilds the scene graph when chart
+          configuration changes. Every time a parent component re-renders, React creates
+          new prop values — including new function objects for inline accessors like{" "}
+          <code>{"xAccessor={d => d.time}"}</code>. Without mitigation, each re-render
+          triggers a full scene rebuild even when nothing meaningful changed.
+        </p>
+        <p>
+          Semiotic handles this automatically via <strong>accessor equivalence checking</strong>.
+          When <code>updateConfig</code> receives new accessor values, it compares them to the
+          previous values using <code>accessorsEquivalent()</code>:
+        </p>
+        <ul>
+          <li><strong>String accessors</strong> — compared by value (<code>"x" === "x"</code>)</li>
+          <li><strong>Same function reference</strong> — identical (<code>fn === fn</code>)</li>
+          <li><strong>Inline arrows with identical source</strong> — compared via <code>.toString()</code></li>
+          <li><strong>Different types</strong> — always treated as changed</li>
+        </ul>
+        <p>
+          This means <code>{"xAccessor={d => d.time}"}</code> written inline in JSX will
+          <em>not</em> trigger a scene rebuild on re-render, as long as the source code
+          is identical each time. However, string accessors remain the most reliable and
+          efficient option.
+        </p>
+
+        <h3>Accessor preference order</h3>
+        <p>From most stable to least:</p>
+        <CodeBlock>{`// 1. String accessor (best) — always stable
+<LineChart xAccessor="time" yAccessor="value" />
+
+// 2. Function defined outside the component — stable reference
+const getX = (d) => d.timestamp / 1000
+function MyChart() {
+  return <LineChart xAccessor={getX} yAccessor="value" />
+}
+
+// 3. useCallback — stable across re-renders
+function MyChart({ divisor }) {
+  const getX = useCallback((d) => d.timestamp / divisor, [divisor])
+  return <LineChart xAccessor={getX} yAccessor="value" />
+}
+
+// 4. Inline arrow (OK) — caught by .toString() heuristic
+<LineChart xAccessor={d => d.timestamp / 1000} yAccessor="value" />`}
+        </CodeBlock>
+
+        <h3>When .toString() does not help</h3>
+        <p>
+          The <code>.toString()</code> comparison catches inline arrows with identical source text.
+          It does <strong>not</strong> help when the function body is the same but it closes over a
+          changing variable:
+        </p>
+        <CodeBlock>{`// WARNING: multiplier changes but the source text is always "d => d.value * multiplier"
+// .toString() sees them as equal even though behavior changed
+function MyChart({ multiplier }) {
+  return <LineChart yAccessor={d => d.value * multiplier} />
+}
+
+// FIX: use useCallback with multiplier in the dependency array
+function MyChart({ multiplier }) {
+  const getY = useCallback((d) => d.value * multiplier, [multiplier])
+  return <LineChart yAccessor={getY} />
+}`}
+        </CodeBlock>
+
+        <h3>diagnoseConfig warning</h3>
+        <p>
+          The <code>diagnoseConfig</code> utility (and <code>npx semiotic-ai --doctor</code>)
+          emits a <code>FUNCTION_ACCESSOR</code> warning when it detects function accessors in
+          your props. This is informational — function accessors work fine, but string accessors
+          are preferred for maximum stability and clarity.
+        </p>
+        <CodeBlock>{`import { diagnoseConfig } from "semiotic/ai"
+
+const result = diagnoseConfig("LineChart", {
+  data: myData,
+  xAccessor: d => d.time,
+  yAccessor: "value",
+})
+// result.diagnoses includes:
+// { code: "FUNCTION_ACCESSOR", severity: "warning",
+//   message: "Function accessor detected: xAccessor. ..." }`}
+        </CodeBlock>
+      </section>
+
+      <section>
+        <h2>MCP Rasterized Output</h2>
+        <p>
+          The Semiotic MCP server's <code>renderChart</code> tool supports both SVG and PNG
+          output formats. SVG is the default. PNG output requires the optional{" "}
+          <code>sharp</code> package.
+        </p>
+        <CodeBlock>{`// MCP tool call with format parameter
+{
+  "component": "LineChart",
+  "props": {
+    "data": [{ "x": 1, "y": 10 }, { "x": 2, "y": 20 }],
+    "xAccessor": "x",
+    "yAccessor": "y"
+  },
+  "format": "png"  // "svg" (default) or "png"
+}`}
+        </CodeBlock>
+
+        <h3>Installing sharp</h3>
+        <p>
+          PNG output uses <a href="https://sharp.pixelplumbing.com/">sharp</a> for SVG-to-PNG
+          conversion. It's listed as an optional dependency — install it when you need PNG:
+        </p>
+        <CodeBlock>{`npm install sharp`}</CodeBlock>
+        <p>
+          If <code>sharp</code> is not installed and <code>format: "png"</code> is requested,
+          the tool returns the SVG output with an installation hint instead of failing.
+        </p>
+
+        <h3>Output format</h3>
+        <p>
+          PNG output is returned as a Base64 data URI string:{" "}
+          <code>data:image/png;base64,...</code>. This can be embedded directly in HTML
+          or saved to a file by decoding the Base64 payload.
+        </p>
+      </section>
+
+      <section>
+        <h2>General Tips</h2>
+        <ul>
+          <li>
+            <strong>Use sub-entries for smaller bundles.</strong>{" "}
+            Import from <code>semiotic/xy</code>, <code>semiotic/ordinal</code>, etc. instead
+            of the main <code>semiotic</code> entry to tree-shake unused chart types.
+            See <Link to="/getting-started">Getting Started</Link>.
+          </li>
+          <li>
+            <strong>Canvas rendering is default.</strong> All Stream Frames and HOC charts
+            render to <code>&lt;canvas&gt;</code> with SVG overlays for annotations and tooltips.
+            This gives better performance than pure SVG for large datasets.
+          </li>
+          <li>
+            <strong>Streaming data uses ring buffers.</strong> The{" "}
+            <code>windowSize</code> prop controls how many points are kept in memory.
+            Older points are evicted automatically.
+          </li>
+          <li>
+            <strong>Push API avoids re-render overhead.</strong> Use{" "}
+            <code>ref.current.push(datum)</code> instead of updating a state array.
+            See <Link to="/features/realtime-encoding">Realtime Encoding</Link>.
+          </li>
+        </ul>
+      </section>
+    </PageLayout>
+  )
+}

src/components/charts/shared/diagnoseConfig.test.ts

@@ -209,6 +209,45 @@ describe("diagnoseConfig", () => {
     expect(diag.severity).toBe("warning")
   })
 
+  it("warns about function accessors", () => {
+    const result = diagnoseConfig("LineChart", {
+      data: [{ x: 1, y: 2 }],
+      xAccessor: (d: any) => d.x,
+      yAccessor: (d: any) => d.y,
+    })
+    const codes = result.diagnoses.map(d => d.code)
+    expect(codes).toContain("FUNCTION_ACCESSOR")
+    const diag = result.diagnoses.find(d => d.code === "FUNCTION_ACCESSOR")!
+    expect(diag.severity).toBe("warning")
+    expect(diag.message).toContain("xAccessor")
+    expect(diag.message).toContain("yAccessor")
+    // ok should still be true since it's only a warning
+    expect(result.ok).toBe(true)
+  })
+
+  it("does not warn about function accessors when only string accessors used", () => {
+    const result = diagnoseConfig("LineChart", {
+      data: [{ x: 1, y: 2 }],
+      xAccessor: "x",
+      yAccessor: "y",
+    })
+    const codes = result.diagnoses.map(d => d.code)
+    expect(codes).not.toContain("FUNCTION_ACCESSOR")
+  })
+
+  it("warns about a single function accessor among strings", () => {
+    const result = diagnoseConfig("BarChart", {
+      data: [{ category: "A", value: 10 }],
+      categoryAccessor: "category",
+      valueAccessor: (d: any) => d.value,
+    })
+    const codes = result.diagnoses.map(d => d.code)
+    expect(codes).toContain("FUNCTION_ACCESSOR")
+    const diag = result.diagnoses.find(d => d.code === "FUNCTION_ACCESSOR")!
+    expect(diag.message).toContain("valueAccessor")
+    expect(diag.message).not.toContain("categoryAccessor")
+  })
+
   it("detects string accessor on heatmap", () => {
     const result = diagnoseConfig("Heatmap", {
       data: [{ x: "Mon", y: 1, value: 10 }],

src/components/stream/OrdinalPipelineStore.accessor.test.ts

@@ -0,0 +1,117 @@
+import { OrdinalPipelineStore } from "./OrdinalPipelineStore"
+import type { OrdinalPipelineConfig } from "./ordinalTypes"
+
+function makeConfig(overrides: Partial<OrdinalPipelineConfig> = {}): OrdinalPipelineConfig {
+  return {
+    chartType: "bar",
+    windowSize: 1000,
+    windowMode: "sliding",
+    extentPadding: 0.05,
+    projection: "vertical",
+    oAccessor: "category",
+    rAccessor: "value",
+    ...overrides
+  }
+}
+
+describe("OrdinalPipelineStore — Accessor Stability", () => {
+  it("does not re-resolve oAccessor when string is unchanged", () => {
+    const store = new OrdinalPipelineStore(makeConfig({ oAccessor: "name" }))
+    const originalGetO = store.getOAccessor()
+
+    store.updateConfig({ oAccessor: "name" })
+    expect(store.getOAccessor()).toBe(originalGetO)
+  })
+
+  it("re-resolves oAccessor when string changes", () => {
+    const store = new OrdinalPipelineStore(makeConfig({ oAccessor: "name" }))
+    const originalGetO = store.getOAccessor()
+
+    store.updateConfig({ oAccessor: "label" })
+    expect(store.getOAccessor()).not.toBe(originalGetO)
+    expect(store.getOAccessor()({ label: "X" })).toBe("X")
+  })
+
+  it("does not re-resolve oAccessor for equivalent inline arrows", () => {
+    const store = new OrdinalPipelineStore(makeConfig({
+      oAccessor: (d: any) => d.name
+    }))
+    const originalGetO = store.getOAccessor()
+
+    // Simulate React re-render: new function, same source
+    store.updateConfig({ oAccessor: (d: any) => d.name })
+    expect(store.getOAccessor()).toBe(originalGetO)
+  })
+
+  it("re-resolves oAccessor when function source changes", () => {
+    const store = new OrdinalPipelineStore(makeConfig({
+      oAccessor: (d: any) => d.name
+    }))
+    const originalGetO = store.getOAccessor()
+
+    store.updateConfig({ oAccessor: (d: any) => d.label })
+    expect(store.getOAccessor()).not.toBe(originalGetO)
+  })
+
+  it("does not re-resolve rAccessor for equivalent string", () => {
+    const store = new OrdinalPipelineStore(makeConfig({ rAccessor: "count" }))
+    const originalGetR = store.getRAccessor()
+
+    store.updateConfig({ rAccessor: "count" })
+    expect(store.getRAccessor()).toBe(originalGetR)
+  })
+
+  it("does not re-resolve rAccessor for equivalent function", () => {
+    const store = new OrdinalPipelineStore(makeConfig({
+      rAccessor: (d: any) => d.count
+    }))
+    const originalGetR = store.getRAccessor()
+
+    store.updateConfig({ rAccessor: (d: any) => d.count })
+    expect(store.getRAccessor()).toBe(originalGetR)
+  })
+
+  it("does not re-resolve stackBy for equivalent string", () => {
+    const store = new OrdinalPipelineStore(makeConfig({
+      stackBy: "group"
+    }))
+
+    // No error, accessor stays stable
+    store.updateConfig({ stackBy: "group" })
+    // Verify store still functions
+    store.ingest({
+      inserts: [{ category: "A", value: 10, group: "X" }],
+      bounded: true
+    })
+    store.computeScene({ width: 200, height: 200 })
+    expect(store.scene.length).toBeGreaterThan(0)
+  })
+
+  it("does not re-resolve colorAccessor for equivalent function", () => {
+    const store = new OrdinalPipelineStore(makeConfig({
+      colorAccessor: (d: any) => d.type
+    }))
+
+    // Simulate re-render
+    store.updateConfig({ colorAccessor: (d: any) => d.type })
+
+    // Verify store still works
+    store.ingest({
+      inserts: [{ category: "A", value: 10, type: "primary" }],
+      bounded: true
+    })
+    store.computeScene({ width: 200, height: 200 })
+    expect(store.scene.length).toBeGreaterThan(0)
+  })
+
+  it("categoryAccessor alias follows same equivalence rules", () => {
+    const store = new OrdinalPipelineStore(makeConfig({
+      oAccessor: undefined,
+      categoryAccessor: "region"
+    }))
+    const originalGetO = store.getOAccessor()
+
+    store.updateConfig({ categoryAccessor: "region" })
+    expect(store.getOAccessor()).toBe(originalGetO)
+  })
+})

src/components/stream/OrdinalPipelineStore.ts

@@ -1000,7 +1000,7 @@ export class OrdinalPipelineStore {
   }
 
   updateConfig(config: Partial<OrdinalPipelineConfig>): void {
-    const prev = this.config
+    const prev = { ...this.config }
 
     if (config.colorScheme !== this.config.colorScheme) {
       this._colorSchemeMap = null