semiotic 3.1.1 → 3.2.0

package/ai/dist/mcp-server.js

@@ -19,6 +19,9 @@
  *     }
  *   }
  * }
+ *
+ * HTTP mode (for remote inspectors / web clients):
+ *   npx semiotic-mcp --http --port 3001
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -56,34 +59,32 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const zod_1 = require("zod");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const http = __importStar(require("http"));
 const renderHOCToSVG_1 = require("./renderHOCToSVG");
 const componentRegistry_1 = require("./componentRegistry");
 const ai_1 = require("semiotic/ai");
 // Load schema.json for version info
 const schemaPath = path.resolve(__dirname, "../schema.json");
 const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
-// Build MCP server
-const server = new mcp_js_1.McpServer({
-    name: "semiotic",
-    version: schema.version || "3.0.0",
-});
 // Build component name → schema lookup from schema.json
 const schemaByComponent = {};
 for (const tool of schema.tools) {
     schemaByComponent[tool.function.name] = tool.function;
 }
-// ── getSchema tool ──────────────────────────────────────────────────────
-// Returns the prop schema for a specific component, or lists all components.
-server.tool("getSchema", `Return the prop schema for a Semiotic chart component. Pass { component: '<name>' } to get its props, or omit component to list all available components. Components marked [renderable] can be passed to renderChart for static SVG output.`, {}, async (args) => {
+const componentNames = Object.keys(componentRegistry_1.COMPONENT_REGISTRY).sort();
+const REPO = "nteract/semiotic";
+async function getSchemaHandler(args) {
     const component = args.component;
     if (!component) {
         const all = Object.keys(schemaByComponent).sort();
         const renderable = new Set(Object.keys(componentRegistry_1.COMPONENT_REGISTRY));
         const list = all.map(name => renderable.has(name) ? `${name} [renderable]` : name);
         return {
-            content: [{ type: "text", text: `Available components (${all.length}):\n${list.join(", ")}\n\nComponents marked [renderable] can be rendered to SVG via renderChart. Others (Realtime*) require a browser environment.\n\nPass { component: '<name>' } to get the prop schema for a specific component.` }],
+            content: [{ type: "text", text: `Available components (${all.length}):\n${list.join(", ")}\n\nComponents marked [renderable] can be rendered to SVG via renderChart (pass theme parameter for styled output). Others (Realtime*) require a browser environment.\n\nAll charts support CSS custom properties for theming (--semiotic-bg, --semiotic-text, --semiotic-grid, etc.) and <ThemeProvider>. Use COLOR_BLIND_SAFE_CATEGORICAL (import from semiotic) for accessible color palettes.\n\nPass { component: '<name>' } to get the prop schema for a specific component.` }],
         };
     }
     const entry = schemaByComponent[component];
@@ -94,14 +95,12 @@ server.tool("getSchema", `Return the prop schema for a Semiotic chart component.
             isError: true,
         };
     }
-    const renderable = componentRegistry_1.COMPONENT_REGISTRY[component] ? "This component can be rendered to SVG via renderChart." : "This component requires a browser environment and cannot be rendered via renderChart.";
+    const renderableNote = componentRegistry_1.COMPONENT_REGISTRY[component] ? "This component can be rendered to SVG via renderChart." : "This component requires a browser environment and cannot be rendered via renderChart.";
     return {
-        content: [{ type: "text", text: `${renderable}\n\n${JSON.stringify(entry, null, 2)}` }],
+        content: [{ type: "text", text: `${renderableNote}\n\n${JSON.stringify(entry, null, 2)}` }],
     };
-});
-// ── suggestChart tool ───────────────────────────────────────────────────
-// Analyzes a data sample and recommends appropriate chart types.
-server.tool("suggestChart", "Recommend Semiotic chart types for a given data sample. Pass { data: [...] } with 1-5 sample objects. Optionally pass { intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy' } to narrow suggestions. Returns ranked recommendations with example props.", {}, async (args) => {
+}
+async function suggestChartHandler(args) {
     const data = args.data;
     const intent = args.intent;
     if (!data || !Array.isArray(data) || data.length === 0) {
@@ -135,8 +134,6 @@ server.tool("suggestChart", "Recommend Semiotic chart types for a given data sam
             numericFields.push(key);
         }
         else if (typeof first === "string") {
-            // Check for dates — require ISO-like pattern (YYYY-MM or YYYY/MM or YYYY-MM-DD, etc.)
-            // to avoid false positives on 4-digit IDs like "1234"
             if (/^\d{4}[-/]\d{2}/.test(first) && !isNaN(Date.parse(first))) {
                 dateFields.push(key);
             }
@@ -144,20 +141,17 @@ server.tool("suggestChart", "Recommend Semiotic chart types for a given data sam
                 stringFields.push(key);
             }
         }
-        // Detect geo fields
         const kl = key.toLowerCase();
         if (kl === "lat" || kl === "latitude")
             geoFields.lat = key;
         if (kl === "lon" || kl === "lng" || kl === "longitude")
             geoFields.lon = key;
-        // Detect network fields
         if (kl === "source" || kl === "from")
             networkFields.source = key;
         if (kl === "target" || kl === "to")
             networkFields.target = key;
         if (kl === "value" || kl === "weight" || kl === "amount")
             networkFields.value = key;
-        // Detect hierarchy fields
         if (kl === "children" || kl === "values")
             hierarchyFields.children = key;
         if (kl === "parent")
@@ -252,11 +246,11 @@ server.tool("suggestChart", "Recommend Semiotic chart types for a given data sam
                 props: { data: "data", categoryAccessor: `"${catField}"`, valueAccessor: `"${valField}"`, stackBy: `"${stringFields[1]}"` },
             });
         }
-        if (data.length >= 10 && (!intent || intent === "distribution")) {
+        if (!intent || intent === "distribution") {
             suggestions.push({
                 component: "Histogram",
                 confidence: "medium",
-                reason: `${data.length}+ data points — histogram shows value distribution`,
+                reason: `Numeric distribution of ${valField} — histogram shows value spread`,
                 props: { data: "data", categoryAccessor: `"${catField}"`, valueAccessor: `"${valField}"` },
             });
         }
@@ -311,25 +305,17 @@ server.tool("suggestChart", "Recommend Semiotic chart types for a given data sam
         const propsStr = Object.entries(s.props).map(([k, v]) => `${k}=${v}`).join(" ");
         return `${i + 1}. **${s.component}** (${s.confidence} confidence)\n   ${s.reason}\n   \`<${s.component} ${propsStr} />\``;
     });
+    // Theming guidance appended to every recommendation
+    const themingTip = `\n---\n**Styling**: All charts respond to CSS custom properties on any ancestor element:\n\`\`\`css\n.my-theme {\n  --semiotic-bg: #fff;           /* chart background */\n  --semiotic-text: #333;         /* primary text */\n  --semiotic-text-secondary: #666; /* tick labels */\n  --semiotic-grid: #e0e0e0;      /* grid lines */\n  --semiotic-border: #e0e0e0;    /* axis lines, borders */\n  --semiotic-font-family: sans-serif;\n  --semiotic-tooltip-bg: rgba(0,0,0,0.85);\n  --semiotic-tooltip-text: white;\n  --semiotic-tooltip-radius: 6px;\n}\n\`\`\`\nOr use \`<ThemeProvider theme="dark">\` / \`<ThemeProvider theme={{ colors: {...}, typography: {...} }}>\`.\nFor accessibility, use \`colorScheme={COLOR_BLIND_SAFE_CATEGORICAL}\` (import from \`semiotic\`) — 8-color palette safe for all forms of color blindness.`;
     return {
-        content: [{ type: "text", text: lines.join("\n\n") }],
+        content: [{ type: "text", text: lines.join("\n\n") + themingTip }],
     };
-});
-// ── renderChart tool ─────────────────────────────────────────────────────
-// Generic tool that renders any Semiotic HOC chart to static SVG.
-// Accepts { component, props } — the single entry point for all chart rendering.
-const componentNames = Object.keys(componentRegistry_1.COMPONENT_REGISTRY).sort();
-server.tool("renderChart", `Render any Semiotic chart to static SVG. Pass { component: '<name>', props: { ... } }. Returns SVG string or validation errors. Available components: ${componentNames.join(", ")}.`, {}, async (args) => {
+}
+async function renderChartHandler(args) {
     const component = args.component;
-    let props;
-    if (args.props) {
-        props = args.props;
-    }
-    else {
-        // Flatten shape: { component, data, ... } — strip component before forwarding
-        const { component: _, ...rest } = args;
-        props = rest;
-    }
+    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(", ")}` }],
@@ -349,23 +335,51 @@ server.tool("renderChart", `Render any Semiotic chart to static SVG. Pass { comp
             isError: true,
         };
     }
+    let svg = result.svg;
+    // Inject theme CSS custom properties into the SVG root element.
+    // We add a <style> block inside the SVG rather than wrapping in a <div>,
+    // because sharp requires pure SVG input for PNG rasterization.
+    if (theme && Object.keys(theme).length > 0) {
+        const validVars = Object.entries(theme)
+            .filter(([k]) => k.startsWith("--semiotic-"))
+            .map(([k, v]) => `${k}: ${v}`)
+            .join("; ");
+        if (validVars) {
+            svg = svg.replace(/<svg([^>]*)>/, `<svg$1><style>:root { ${validVars} }</style>`);
+        }
+    }
+    // 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: result.svg }],
+        content: [{ type: "text", text: svg }],
     };
-});
-// ── diagnoseConfig tool ──────────────────────────────────────────────────
-// Anti-pattern detector: checks for common failure modes and returns
-// actionable fix instructions.
-server.tool("diagnoseConfig", "Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, etc). Pass { component: 'LineChart', props: { ... } }. Returns structured diagnoses with fix instructions.", {}, async (args) => {
+}
+async function diagnoseConfigHandler(args) {
     const component = args.component;
-    let props;
-    if (args.props) {
-        props = args.props;
-    }
-    else {
-        const { component: _, ...rest } = args;
-        props = rest;
-    }
+    const props = args.props ?? {};
     if (!component) {
         return {
             content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
@@ -374,13 +388,13 @@ server.tool("diagnoseConfig", "Diagnose a Semiotic chart configuration for commo
     }
     const result = (0, ai_1.diagnoseConfig)(component, props);
     if (result.ok) {
-        const warnings = result.diagnoses.filter(d => d.severity === "warning");
+        const warnings = result.diagnoses.filter((d) => d.severity === "warning");
         const msg = warnings.length > 0
-            ? `Configuration looks good with ${warnings.length} warning(s):\n${warnings.map(w => `⚠ [${w.code}] ${w.message}\n  Fix: ${w.fix}`).join("\n")}`
+            ? `Configuration looks good with ${warnings.length} warning(s):\n${warnings.map((w) => `⚠ [${w.code}] ${w.message}\n  Fix: ${w.fix}`).join("\n")}`
             : `✓ Configuration looks good — no issues detected.`;
         return { content: [{ type: "text", text: msg }] };
     }
-    const lines = result.diagnoses.map(d => {
+    const lines = result.diagnoses.map((d) => {
         const icon = d.severity === "error" ? "✗" : "⚠";
         const fixLine = d.fix ? `\n  Fix: ${d.fix}` : "";
         return `${icon} [${d.code}] ${d.message}${fixLine}`;
@@ -389,12 +403,8 @@ server.tool("diagnoseConfig", "Diagnose a Semiotic chart configuration for commo
         content: [{ type: "text", text: lines.join("\n") }],
         isError: true,
     };
-});
-// ── reportIssue tool ─────────────────────────────────────────────────────
-// Generates a pre-filled GitHub issue URL for bug reports or feature requests.
-// The user (or AI agent) can open the URL to submit — no auth needed.
-const REPO = "nteract/semiotic";
-server.tool("reportIssue", "Generate a GitHub issue URL for Semiotic bug reports or feature requests. Pass { title, body, labels? }. Returns a URL the user can open to submit. For rendering bugs, include the component name, props summary, and any diagnoseConfig output in the body.", {}, async (args) => {
+}
+async function reportIssueHandler(args) {
     const title = args.title;
     const body = args.body;
     const labels = args.labels;
@@ -416,11 +426,168 @@ server.tool("reportIssue", "Generate a GitHub issue URL for Semiotic bug reports
     return {
         content: [{ type: "text", text: `Open this URL to submit the issue:\n\n${url}` }],
     };
-});
-// Start the server
+}
+// Named theme presets (inlined to avoid runtime dependency on semiotic-themes bundle)
+const THEME_PRESET_NAMES = [
+    "light", "dark", "high-contrast",
+    "pastels", "pastels-dark",
+    "bi-tool", "bi-tool-dark",
+    "italian", "italian-dark",
+    "tufte", "tufte-dark",
+    "journalist", "journalist-dark",
+    "playful", "playful-dark",
+];
+async function applyThemeHandler(args) {
+    const name = args.name;
+    if (!name) {
+        return {
+            content: [{ type: "text", text: `Available theme presets:\n${THEME_PRESET_NAMES.join(", ")}\n\nPass { name: "tufte" } to get the CSS custom properties and ThemeProvider usage for that theme.\n\nLight-mode presets: ${THEME_PRESET_NAMES.filter(n => !n.includes("dark")).join(", ")}\nDark-mode presets: ${THEME_PRESET_NAMES.filter(n => n.includes("dark")).join(", ")}` }],
+        };
+    }
+    if (!THEME_PRESET_NAMES.includes(name)) {
+        return {
+            content: [{ type: "text", text: `Unknown theme "${name}". Available: ${THEME_PRESET_NAMES.join(", ")}` }],
+            isError: true,
+        };
+    }
+    const usage = [
+        `## Theme: "${name}"`,
+        "",
+        "### Option 1: ThemeProvider (recommended)",
+        "```jsx",
+        `import { ThemeProvider } from "semiotic"`,
+        `<ThemeProvider theme="${name}">`,
+        `  <LineChart ... />`,
+        `</ThemeProvider>`,
+        "```",
+        "",
+        "### Option 2: Import the theme object",
+        "```jsx",
+        `import { ${name.replace(/-./g, c => c[1].toUpperCase()).replace(/^./, c => c.toUpperCase()).replace(/Dark$/, '_DARK').replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase()} } from "semiotic/themes"`,
+        `<ThemeProvider theme={themeObject}>`,
+        `  <BarChart ... />`,
+        `</ThemeProvider>`,
+        "```",
+        "",
+        "### Option 3: CSS custom properties (no React required)",
+        "```jsx",
+        `import { themeToCSS } from "semiotic/themes"`,
+        `import { ${name.replace(/-./g, c => c[1].toUpperCase()).replace(/^./, c => c.toUpperCase()).replace(/Dark$/, '_DARK').replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase()} } from "semiotic/themes"`,
+        `const css = themeToCSS(themeObject, ".my-charts")`,
+        "// Outputs CSS custom properties string for embedding in a stylesheet",
+        "```",
+        "",
+        "### Option 4: Design tokens JSON",
+        "```jsx",
+        `import { themeToTokens } from "semiotic/themes"`,
+        `const tokens = themeToTokens(themeObject)`,
+        "// Style Dictionary / DTCG-compatible token format",
+        "```",
+        "",
+        "For accessibility, consider `\"high-contrast\"` which uses `COLOR_BLIND_SAFE_CATEGORICAL` (Wong 2011 palette).",
+    ];
+    return {
+        content: [{ type: "text", text: usage.join("\n") }],
+    };
+}
+// ── Server factory ───────────────────────────────────────────────────────
+// Creates a fresh McpServer with all tools registered.
+// HTTP mode needs one instance per session (McpServer can only connect to one transport).
+// Stdio mode uses a single instance.
+function createServer() {
+    const srv = new mcp_js_1.McpServer({
+        name: "semiotic",
+        version: schema.version || "3.0.0",
+    });
+    srv.tool("getSchema", `Return the prop schema for a Semiotic chart component. Pass { component: '<name>' } to get its props, or omit component to list all available components. Components marked [renderable] can be passed to renderChart for static SVG output.`, { component: zod_1.z.string().optional().describe("Component name, e.g. 'LineChart'. Omit to list all.") }, getSchemaHandler);
+    srv.tool("suggestChart", "Recommend Semiotic chart types for a given data sample. Pass { data: [...] } with 1-5 sample objects. Optionally pass intent to narrow suggestions. Returns ranked recommendations with example props.", {
+        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 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'"),
+        props: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
+    }, diagnoseConfigHandler);
+    srv.tool("reportIssue", "Generate a GitHub issue URL for Semiotic bug reports or feature requests. Returns a URL the user can open to submit. For rendering bugs, include the component name, props summary, and any diagnoseConfig output in the body.", {
+        title: zod_1.z.string().describe("Issue title, e.g. 'Bug: BarChart tooltip shows undefined'"),
+        body: zod_1.z.string().optional().describe("Issue body with details, reproduction steps, diagnoseConfig output"),
+        labels: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe("GitHub labels, e.g. ['bug'] or 'bug'"),
+    }, reportIssueHandler);
+    srv.tool("applyTheme", `Get usage instructions for a named Semiotic theme preset. Returns ThemeProvider examples, CSS custom properties, and design token export patterns. Available themes: ${THEME_PRESET_NAMES.join(", ")}.`, {
+        name: zod_1.z.string().optional().describe("Theme preset name, e.g. 'tufte', 'pastels-dark', 'bi-tool'. Omit to list all available themes."),
+    }, applyThemeHandler);
+    return srv;
+}
+// ── Startup ──────────────────────────────────────────────────────────────
+const cliArgs = process.argv.slice(2);
+const httpMode = cliArgs.includes("--http");
+const portFlagIndex = cliArgs.indexOf("--port");
+const parsedPort = portFlagIndex !== -1 && cliArgs[portFlagIndex + 1] != null
+    ? parseInt(cliArgs[portFlagIndex + 1], 10)
+    : NaN;
+const port = Number.isFinite(parsedPort) ? parsedPort : 3001;
 async function main() {
-    const transport = new stdio_js_1.StdioServerTransport();
-    await server.connect(transport);
+    if (httpMode) {
+        // HTTP mode — session-based, one server+transport per session
+        const sessions = new Map();
+        const httpServer = http.createServer(async (req, res) => {
+            // CORS headers for browser-based inspectors
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id");
+            res.setHeader("Access-Control-Expose-Headers", "mcp-session-id");
+            if (req.method === "OPTIONS") {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            const sessionId = req.headers["mcp-session-id"];
+            if (sessionId && sessions.has(sessionId)) {
+                // Existing session — route to its transport
+                const session = sessions.get(sessionId);
+                await session.transport.handleRequest(req, res);
+            }
+            else if (!sessionId) {
+                // New session — create server + transport
+                const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => `semiotic-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                });
+                const srv = createServer();
+                await srv.connect(transport);
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid)
+                        sessions.delete(sid);
+                };
+                await transport.handleRequest(req, res);
+                const sid = transport.sessionId;
+                if (sid) {
+                    sessions.set(sid, { server: srv, transport });
+                }
+            }
+            else {
+                // Session ID provided but not found — stale session
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Unknown session. Send a request without mcp-session-id to start a new session." }, id: null }));
+            }
+        });
+        httpServer.listen(port, () => {
+            console.error(`Semiotic MCP server (HTTP) listening on http://localhost:${port}`);
+            console.error("Tools: getSchema, suggestChart, renderChart, diagnoseConfig, reportIssue");
+        });
+    }
+    else {
+        // Default: stdio mode for Claude Desktop, Claude Code, Cursor, etc.
+        const srv = createServer();
+        const transport = new stdio_js_1.StdioServerTransport();
+        await srv.connect(transport);
+    }
 }
 main().catch((err) => {
     console.error("MCP server error:", err);

package/ai/dist/renderHOCToSVG.js

@@ -53,12 +53,14 @@ function renderHOCToSVG(componentName, props) {
             error: `Unknown component "${componentName}". Available: ${Object.keys(componentRegistry_1.COMPONENT_REGISTRY).join(", ")}`,
         };
     }
-    // Validate props
+    // Validate props (skip for components not in the validation map, e.g. geo)
     const validation = (0, ai_1.validateProps)(componentName, props);
-    if (!validation.valid) {
+    const errors = validation.errors ?? [];
+    const isUnknownComponentOnly = errors.length === 1 && errors[0].startsWith("Unknown component");
+    if (!validation.valid && !isUnknownComponentOnly) {
         return {
             svg: null,
-            error: `Validation errors:\n${validation.errors.join("\n")}`,
+            error: `Validation errors:\n${errors.join("\n")}`,
         };
     }
     // Disable hover (not useful in static SVG)

package/ai/examples.md

@@ -902,3 +902,96 @@ const containerRef = useRef<HTMLDivElement>(null)
 ```
 
 Key: `exportChart(wrapperDiv, { format, filename, scale, background })`. It queries the wrapper for canvas and SVG elements internally. Default format: PNG with 2x scale.
+
+---
+
+## Theming & Brand Styling
+
+### CSS Custom Properties (no React context needed)
+
+```jsx
+// Dark theme via CSS custom properties on a wrapper div
+<div style={{
+  "--semiotic-bg": "#1a1a2e",
+  "--semiotic-text": "#ededed",
+  "--semiotic-text-secondary": "#aaa",
+  "--semiotic-grid": "#333",
+  "--semiotic-border": "#555",
+  "--semiotic-font-family": "'Georgia', serif",
+  "--semiotic-tooltip-bg": "#1a1a2e",
+  "--semiotic-tooltip-text": "#ededed",
+  "--semiotic-tooltip-radius": "8px",
+  "--semiotic-tooltip-shadow": "0 4px 12px rgba(0,0,0,0.4)",
+  "--semiotic-primary": "#ff6b6b",
+  "--semiotic-focus": "#ff6b6b",
+}}>
+  <LineChart
+    data={[{ x: 1, y: 10 }, { x: 2, y: 20 }, { x: 3, y: 15 }]}
+    xAccessor="x" yAccessor="y"
+    showGrid
+    annotations={[{ type: "y-threshold", value: 18, label: "Target" }]}
+  />
+</div>
+```
+
+### ThemeProvider (React context)
+
+```jsx
+import { ThemeProvider, DARK_THEME, COLOR_BLIND_SAFE_CATEGORICAL } from "semiotic"
+
+// Preset dark theme
+<ThemeProvider theme="dark">
+  <BarChart data={data} categoryAccessor="name" valueAccessor="value" />
+</ThemeProvider>
+
+// Custom brand theme (partial merge with defaults)
+<ThemeProvider theme={{
+  mode: "light",
+  colors: {
+    primary: "#cc0000",
+    categorical: ["#cc0000", "#333333", "#c8a415", "#4682b4"],
+    background: "#fafafa",
+    text: "#1a1a1a",
+    textSecondary: "#666",
+    grid: "#e0e0e0",
+    border: "#e0e0e0",
+  },
+  typography: {
+    fontFamily: "'Helvetica Neue', Helvetica, Arial, sans-serif",
+    titleSize: 16, labelSize: 12, tickSize: 10,
+  },
+  tooltip: {
+    background: "#fafafa",
+    text: "#1a1a1a",
+    borderRadius: "4px",
+  },
+}}>
+  <GroupedBarChart data={data} categoryAccessor="quarter" valueAccessor="revenue"
+    groupBy="region" colorBy="region" showGrid showLegend />
+</ThemeProvider>
+
+// Color-blind safe palette (Wong 2011 — 8 colors)
+<Scatterplot data={data} xAccessor="x" yAccessor="y"
+  colorBy="category" colorScheme={COLOR_BLIND_SAFE_CATEGORICAL} />
+```
+
+### Annotations with Theme Colors
+
+```jsx
+// Annotations inherit --semiotic-primary and --semiotic-text-secondary from theme
+<LineChart
+  data={salesData}
+  xAccessor="month" yAccessor="revenue"
+  annotations={[
+    // Threshold line — defaults to --semiotic-primary if no color set
+    { type: "y-threshold", value: 50000, label: "Q3 Target" },
+    // Widget annotation at specific data point
+    { type: "widget", month: "Jul", revenue: 72000, dy: -15, content: (
+      <span style={{ fontSize: 11, fontWeight: 700 }}>Record month</span>
+    )},
+    // Enclose a cluster of outliers
+    { type: "enclose", coordinates: outlierPoints, label: "Outlier cluster", padding: 15 },
+  ]}
+  showGrid
+/>
+```