carbon-tokenization

Running

tfrere HF Staff Cursor commited on 22 days ago

Commit

27abbe5

1 Parent(s): 3afbbdf

feat(embed-studio): make agent-generated charts theme-aware

The iframe already supports live light/dark swap via CSS variables and
a postMessage(setTheme) hot-swap, but the LLM kept generating charts
that hardcode colours into SVG attributes (fill="#333", stroke="black",
...). Those values can't be overridden by the parent's data-theme
attribute, so the chart looked correct on whatever theme the model
guessed and broken on the other one.

Two complementary fixes:

1. Forward the current theme (light/dark) from EmbedStudio through
useEmbedChat into the request context, and surface it in the
system prompt as a "Current theme" section. The model now knows
which background it's painting against and can self-correct.

2. Rewrite the "Colors & theming" section of the embed system prompt
with a concrete CSS pattern (scoped .d3-* rules driving fill/stroke
via var(--text-color), --axis-color, --grid-color, ...) and an
explicit ban on hardcoded SVG colour attributes. Add a hint about
window.__chartRerender for JS-driven palettes.

No public API change - the new context.theme field is opt-in and the
backend gracefully falls back to no theme block when it's missing.

Co-authored-by: Cursor <cursoragent@cursor.com>

Files changed (4) hide show

backend/src/agent/embed-chat.ts +3 -0
backend/src/agent/embed-system-prompt.ts +82 -8
frontend/src/components/EmbedStudio.tsx +1 -1
frontend/src/hooks/useEmbedChat.ts +14 -1

backend/src/agent/embed-chat.ts CHANGED Viewed

@@ -3,6 +3,7 @@ import {
   BANNER_SYSTEM_PROMPT,
   buildEmbedContext,
   buildDataFilesContext,
 } from "./embed-system-prompt.js";
 import { embedTools } from "./embed-tools.js";
 import { streamChatResponse } from "./stream-handler.js";
@@ -14,6 +15,7 @@ export async function handleEmbedChat(req: Request, res: Response) {
   const isBanner = Boolean(context?.isBanner);
   const isScratch = Boolean(context?.isScratch);
   const dataFilesBlock = buildDataFilesContext(context?.dataFiles);
   const parts = [EMBED_SYSTEM_PROMPT];
   if (isBanner) parts.push(BANNER_SYSTEM_PROMPT);
@@ -26,6 +28,7 @@ export async function handleEmbedChat(req: Request, res: Response) {
         "underlying file and keep the document in sync.",
     );
   }
   if (contextBlock) parts.push(`## Current chart\n\n${contextBlock}`);
   if (dataFilesBlock) parts.push(`## Attached data\n\n${dataFilesBlock}`);
   const systemPrompt = parts.join("\n\n");

   BANNER_SYSTEM_PROMPT,
   buildEmbedContext,
   buildDataFilesContext,
+  buildThemeContext,
 } from "./embed-system-prompt.js";
 import { embedTools } from "./embed-tools.js";
 import { streamChatResponse } from "./stream-handler.js";
   const isBanner = Boolean(context?.isBanner);
   const isScratch = Boolean(context?.isScratch);
   const dataFilesBlock = buildDataFilesContext(context?.dataFiles);
+  const themeBlock = buildThemeContext(context?.theme);
   const parts = [EMBED_SYSTEM_PROMPT];
   if (isBanner) parts.push(BANNER_SYSTEM_PROMPT);
         "underlying file and keep the document in sync.",
     );
   }
+  if (themeBlock) parts.push(themeBlock);
   if (contextBlock) parts.push(`## Current chart\n\n${contextBlock}`);
   if (dataFilesBlock) parts.push(`## Attached data\n\n${dataFilesBlock}`);
   const systemPrompt = parts.join("\n\n");

backend/src/agent/embed-system-prompt.ts CHANGED Viewed

@@ -80,14 +80,63 @@ Every chart is a self-contained HTML fragment with:
 \`\`\`
 ### Colors & theming (MANDATORY)
-- Get colors from \`window.ColorPalettes\`:
-  - \`ColorPalettes.getColors('categorical', 8)\` - 8-color categorical palette
-  - \`ColorPalettes.getColors('sequential', 8)\` - sequential blues
-  - \`ColorPalettes.getColors('diverging', 9)\` - red-blue diverging
-  - \`ColorPalettes.getPrimary()\` - current primary accent color
-- Use CSS variables for theming: \`--primary-color\`, \`--text-color\`, \`--muted-color\`, \`--surface-bg\`, \`--border-color\`
-- Axis/tick/grid: \`--axis-color\`, \`--tick-color\`, \`--grid-color\`
-- NEVER hardcode color arrays
 ### Layout rules
 - SVG for chart primitives (marks, axes, gridlines) only
@@ -162,6 +211,31 @@ export function buildEmbedContext(embedHtml?: string): string {
   return `<embed>\n${embedHtml}\n</embed>`;
 }
 function formatDataFileLine(file: DataFileMeta): string {
   const sizeKb = (file.size / 1024).toFixed(1);
   const rows = file.rowCount !== undefined ? ` rows=${file.rowCount}` : "";

 \`\`\`
 ### Colors & theming (MANDATORY)
+The host iframe ships with both **light** and **dark** themes, switched
+live by the user via a \`data-theme\` attribute on \`<html>\`. Your chart
+MUST adapt to both without re-rendering.
+**Categorical / sequential / diverging palettes** - get from
+\`window.ColorPalettes\`. The palettes are tuned to read on both light
+and dark backgrounds:
+- \`ColorPalettes.getColors('categorical', 8)\`
+- \`ColorPalettes.getColors('sequential', 8)\`
+- \`ColorPalettes.getColors('diverging', 9)\`
+- \`ColorPalettes.getPrimary()\` - current primary accent color
+**Text / axes / grid / surfaces** - drive them with CSS variables, NEVER
+with SVG \`fill=\` / \`stroke=\` / inline JS color strings. SVG presentation
+attributes don't parse \`var(--*)\`, so you MUST either:
+1. **Set them in the scoped \`<style>\` block (preferred)** - the
+   browser hot-swaps them when the theme flips, no JS needed:
+   \`\`\`css
+   .d3-yourname { color: var(--text-color); }
+   .d3-yourname .axis path,
+   .d3-yourname .axis line { stroke: var(--axis-color); }
+   .d3-yourname .axis text  { fill: var(--tick-color); }
+   .d3-yourname .grid line  { stroke: var(--grid-color); }
+   .d3-yourname .tooltip    { background: var(--surface-bg); color: var(--text-color); border: 1px solid var(--border-color); }
+   \`\`\`
+2. **Use \`currentColor\`** on SVG elements that should follow the
+   container's CSS \`color\`:
+   \`\`\`js
+   svg.append('text').attr('fill', 'currentColor')...
+   \`\`\`
+Available CSS variables (light + dark values are pre-defined):
+\`--text-color\`, \`--muted-color\`, \`--surface-bg\`, \`--page-bg\`,
+\`--border-color\`, \`--axis-color\`, \`--tick-color\`, \`--grid-color\`,
+\`--primary-color\`.
+**Forbidden patterns** (they freeze the chart on one theme):
+- \`fill="#333"\`, \`stroke="black"\`, \`d3.color('white')\`, \`'rgba(0,0,0,.5)'\`
+  for axes / text / grid / tooltips.
+- Reading \`getComputedStyle(...)\` once at mount and baking the value
+  into attributes. CSS handles it; don't reinvent it.
+- Conditional palettes based on \`document.documentElement.dataset.theme\`
+  for axes/text - just use the CSS vars above.
+**Live theme swap**: if your chart paints categorical / sequential
+colours via JS (which is fine), define \`window.__chartRerender =
+function(){ /* re-run draw() */ }\` so the host can re-tint when the
+user flips the theme. CSS-driven properties (text, axes, grid) update
+automatically and don't need this.
+NEVER hardcode categorical palettes - always go through
+\`window.ColorPalettes\`.
 ### Layout rules
 - SVG for chart primitives (marks, axes, gridlines) only
   return `<embed>\n${embedHtml}\n</embed>`;
 }
+/**
+ * Tell the agent which theme the user is currently looking at, so it
+ * can sanity-check its colour choices in context (e.g. "is this axis
+ * label readable on the current background?") and know which variant
+ * to debug visually. The CSS variables already cover both themes, but
+ * this also surfaces accidental hardcoded colours early - the agent
+ * will see e.g. "current theme: dark" and notice if it just wrote
+ * `fill="#000"`.
+ */
+export function buildThemeContext(theme?: string): string {
+  const t = theme === "dark" ? "dark" : theme === "light" ? "light" : null;
+  if (!t) return "";
+  return [
+    "## Current theme",
+    "",
+    `The user is currently viewing the article in **${t}** mode. The`,
+    "iframe automatically swaps CSS variables when the theme flips, so",
+    "any chart that drives axes/text/grid via the `--*` variables (see",
+    "the Colors & theming section) will adapt without any extra work.",
+    "Use this as a sanity check: if you ever feel tempted to hardcode a",
+    `colour, ask yourself "would this still be readable in ${t === "dark" ? "light" : "dark"} mode?" - the`,
+    "answer is almost always no.",
+  ].join("\n");
+}
 function formatDataFileLine(file: DataFileMeta): string {
   const sizeKb = (file.size / 1024).toFixed(1);
   const rows = file.rowCount !== undefined ? ` rows=${file.rowCount}` : "";

frontend/src/components/EmbedStudio.tsx CHANGED Viewed

@@ -162,7 +162,7 @@ export function EmbedStudio({
   activeRef.current = activeFrame;
   const data = useEmbedData({ dataStore, userId });
-  const chat = useEmbedChat({ embedStore, dataStore, src, modelRef, userId, onRename });
   const selectedFile = selectedDataFile ? data.getFile(selectedDataFile) : undefined;

   activeRef.current = activeFrame;
   const data = useEmbedData({ dataStore, userId });
+  const chat = useEmbedChat({ embedStore, dataStore, src, modelRef, userId, isDark, onRename });
   const selectedFile = selectedDataFile ? data.getFile(selectedDataFile) : undefined;

frontend/src/hooks/useEmbedChat.ts CHANGED Viewed

@@ -16,6 +16,13 @@ interface UseEmbedChatOptions {
   src: string;
   modelRef: React.RefObject<string>;
   userId: string;
   /**
    * Called when the agent picks a descriptive filename via createEmbed.
    * Parent is expected to update the htmlEmbed node's src attribute in
@@ -73,7 +80,7 @@ function scopeKey(src: string): string {
   return `embed:${src}`;
 }
-export function useEmbedChat({ embedStore, dataStore, src, modelRef, userId, onRename }: UseEmbedChatOptions) {
   const [input, setInput] = useState("");
   // srcRef is the source of truth for the active embed filename. It
   // starts from the `src` prop but may change mid-session when the
@@ -98,6 +105,11 @@ export function useEmbedChat({ embedStore, dataStore, src, modelRef, userId, onR
   // restored messages end with completed tool calls.
   const userHasSentRef = useRef(false);
   const getEmbedContext = useCallback(() => {
     if (!embedStore || !srcRef.current) return {};
     const currentSrc = srcRef.current;
@@ -123,6 +135,7 @@ export function useEmbedChat({ embedStore, dataStore, src, modelRef, userId, onR
       isBanner,
       isScratch,
       dataFiles,
     };
   }, [embedStore, dataStore]);

   src: string;
   modelRef: React.RefObject<string>;
   userId: string;
+  /**
+   * Current article theme (light/dark). Forwarded to the agent so it
+   * can sanity-check its colour choices and bake theme-aware CSS into
+   * generated charts (instead of hardcoding axis/text colours that
+   * only happen to look right under one theme).
+   */
+  isDark?: boolean;
   /**
    * Called when the agent picks a descriptive filename via createEmbed.
    * Parent is expected to update the htmlEmbed node's src attribute in
   return `embed:${src}`;
 }
+export function useEmbedChat({ embedStore, dataStore, src, modelRef, userId, isDark, onRename }: UseEmbedChatOptions) {
   const [input, setInput] = useState("");
   // srcRef is the source of truth for the active embed filename. It
   // starts from the `src` prop but may change mid-session when the
   // restored messages end with completed tool calls.
   const userHasSentRef = useRef(false);
+  // Track the current theme via ref so getEmbedContext always reads the
+  // latest value without forcing a callback identity churn on toggle.
+  const isDarkRef = useRef(!!isDark);
+  isDarkRef.current = !!isDark;
   const getEmbedContext = useCallback(() => {
     if (!embedStore || !srcRef.current) return {};
     const currentSrc = srcRef.current;
       isBanner,
       isScratch,
       dataFiles,
+      theme: isDarkRef.current ? "dark" : "light",
     };
   }, [embedStore, dataStore]);