semiotic 3.5.1 → 3.5.3

package/ai/dist/mcp-server.js

@@ -3106,6 +3106,9 @@ var require_utils = __commonJS({
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+    var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
+    var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
+    var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
     function stringArrayToHexStripped(input) {
       let acc = "";
       let code = 0;
@@ -3298,27 +3301,77 @@ var require_utils = __commonJS({
       }
       return output.join("");
     }
-    function normalizeComponentEncoding(component, esc2) {
-      const func = esc2 !== true ? escape : unescape;
-      if (component.scheme !== void 0) {
-        component.scheme = func(component.scheme);
-      }
-      if (component.userinfo !== void 0) {
-        component.userinfo = func(component.userinfo);
-      }
-      if (component.host !== void 0) {
-        component.host = func(component.host);
+    var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
+    var HOST_DELIM_RE = /[@/?#:]/g;
+    var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
+    function reescapeHostDelimiters(host, isIP) {
+      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+      re.lastIndex = 0;
+      return host.replace(re, (ch) => HOST_DELIMS[ch]);
+    }
+    function normalizePercentEncoding(input, decodeUnreserved = false) {
+      if (input.indexOf("%") === -1) {
+        return input;
       }
-      if (component.path !== void 0) {
-        component.path = func(component.path);
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decodeUnreserved && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        output += input[i];
       }
-      if (component.query !== void 0) {
-        component.query = func(component.query);
+      return output;
+    }
+    function normalizePathEncoding(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decoded !== "." && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        if (isPathCharacter(input[i])) {
+          output += input[i];
+        } else {
+          output += escape(input[i]);
+        }
       }
-      if (component.fragment !== void 0) {
-        component.fragment = func(component.fragment);
+      return output;
+    }
+    function escapePreservingEscapes(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            output += "%" + hex3.toUpperCase();
+            i += 2;
+            continue;
+          }
+        }
+        output += escape(input[i]);
       }
-      return component;
+      return output;
     }
     function recomposeAuthority(component) {
       const uriTokens = [];
@@ -3333,7 +3386,7 @@ var require_utils = __commonJS({
           if (ipV6res.isIPV6 === true) {
             host = `[${ipV6res.escapedHost}]`;
           } else {
-            host = component.host;
+            host = reescapeHostDelimiters(host, false);
           }
         }
         uriTokens.push(host);
@@ -3347,7 +3400,10 @@ var require_utils = __commonJS({
     module2.exports = {
       nonSimpleDomain,
       recomposeAuthority,
-      normalizeComponentEncoding,
+      reescapeHostDelimiters,
+      normalizePercentEncoding,
+      normalizePathEncoding,
+      escapePreservingEscapes,
       removeDotSegments,
       isIPv4,
       isUUID,
@@ -3571,12 +3627,12 @@ var require_schemes = __commonJS({
 var require_fast_uri = __commonJS({
   "node_modules/fast-uri/index.js"(exports2, module2) {
     "use strict";
-    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizeComponentEncoding, isIPv4, nonSimpleDomain } = require_utils();
+    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
     function normalize(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
-        serialize(parse3(uri, options), options);
+        normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
         parse3(serialize(uri, options), options);
@@ -3643,19 +3699,9 @@ var require_fast_uri = __commonJS({
       return target;
     }
     function equal(uriA, uriB, options) {
-      if (typeof uriA === "string") {
-        uriA = unescape(uriA);
-        uriA = serialize(normalizeComponentEncoding(parse3(uriA, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriA === "object") {
-        uriA = serialize(normalizeComponentEncoding(uriA, true), { ...options, skipEscape: true });
-      }
-      if (typeof uriB === "string") {
-        uriB = unescape(uriB);
-        uriB = serialize(normalizeComponentEncoding(parse3(uriB, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriB === "object") {
-        uriB = serialize(normalizeComponentEncoding(uriB, true), { ...options, skipEscape: true });
-      }
-      return uriA.toLowerCase() === uriB.toLowerCase();
+      const normalizedA = normalizeComparableURI(uriA, options);
+      const normalizedB = normalizeComparableURI(uriB, options);
+      return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA.toLowerCase() === normalizedB.toLowerCase();
     }
     function serialize(cmpts, opts) {
       const component = {
@@ -3680,12 +3726,12 @@ var require_fast_uri = __commonJS({
       if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(component, options);
       if (component.path !== void 0) {
         if (!options.skipEscape) {
-          component.path = escape(component.path);
+          component.path = escapePreservingEscapes(component.path);
           if (component.scheme !== void 0) {
             component.path = component.path.split("%3A").join(":");
           }
         } else {
-          component.path = unescape(component.path);
+          component.path = normalizePercentEncoding(component.path);
         }
       }
       if (options.reference !== "suffix" && component.scheme) {
@@ -3720,7 +3766,16 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
-    function parse3(uri, opts) {
+    function getParseError(parsed, matches) {
+      if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
+        return 'URI path must start with "/" when authority is present.';
+      }
+      if (typeof parsed.port === "number" && (parsed.port < 0 || parsed.port > 65535)) {
+        return "URI port is malformed.";
+      }
+      return void 0;
+    }
+    function parseWithStatus(uri, opts) {
       const options = Object.assign({}, opts);
       const parsed = {
         scheme: void 0,
@@ -3731,6 +3786,7 @@ var require_fast_uri = __commonJS({
         query: void 0,
         fragment: void 0
       };
+      let malformedAuthorityOrPort = false;
       let isIP = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
@@ -3751,6 +3807,11 @@ var require_fast_uri = __commonJS({
         if (isNaN(parsed.port)) {
           parsed.port = matches[5];
         }
+        const parseError = getParseError(parsed, matches);
+        if (parseError !== void 0) {
+          parsed.error = parsed.error || parseError;
+          malformedAuthorityOrPort = true;
+        }
         if (parsed.host) {
           const ipv4result = isIPv4(parsed.host);
           if (ipv4result === false) {
@@ -3789,14 +3850,18 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = unescape(parsed.host);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
             }
           }
           if (parsed.path) {
-            parsed.path = escape(unescape(parsed.path));
+            parsed.path = normalizePathEncoding(parsed.path);
           }
           if (parsed.fragment) {
-            parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            try {
+              parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            } catch {
+              parsed.error = parsed.error || "URI malformed";
+            }
           }
         }
         if (schemeHandler && schemeHandler.parse) {
@@ -3805,7 +3870,29 @@ var require_fast_uri = __commonJS({
       } else {
         parsed.error = parsed.error || "URI can not be parsed.";
       }
-      return parsed;
+      return { parsed, malformedAuthorityOrPort };
+    }
+    function parse3(uri, opts) {
+      return parseWithStatus(uri, opts).parsed;
+    }
+    function normalizeString(uri, opts) {
+      return normalizeStringWithStatus(uri, opts).normalized;
+    }
+    function normalizeStringWithStatus(uri, opts) {
+      const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
+      return {
+        normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
+        malformedAuthorityOrPort
+      };
+    }
+    function normalizeComparableURI(uri, opts) {
+      if (typeof uri === "string") {
+        const { normalized, malformedAuthorityOrPort } = normalizeStringWithStatus(uri, opts);
+        return malformedAuthorityOrPort ? void 0 : normalized;
+      }
+      if (typeof uri === "object") {
+        return serialize(uri, opts);
+      }
     }
     var fastUri = {
       SCHEMES,
@@ -6808,6 +6895,7 @@ var require_componentMetadata = __commonJS({
       xy: [
         "LineChart",
         "AreaChart",
+        "DifferenceChart",
         "StackedAreaChart",
         "Scatterplot",
         "QuadrantChart",
@@ -6839,6 +6927,7 @@ var require_componentMetadata = __commonJS({
       network: [
         "ForceDirectedGraph",
         "SankeyDiagram",
+        "ProcessSankey",
         "ChordDiagram",
         "TreeDiagram",
         "Treemap",
@@ -6934,6 +7023,7 @@ var require_componentMetadata = __commonJS({
 var require_chartSuggestions = __commonJS({
   "ai/chartSuggestions.cjs"(exports2, module2) {
     "use strict";
+    var path2 = require("path");
     var VALID_INTENTS = [
       "comparison",
       "trend",
@@ -6945,6 +7035,69 @@ var require_chartSuggestions = __commonJS({
       "hierarchy"
     ];
     var MAX_SAMPLE_SIZE = 5;
+    var _capabilityMatrix = null;
+    var _capabilityMatrixLoaded = false;
+    function loadCapabilityMatrix() {
+      if (_capabilityMatrixLoaded) return _capabilityMatrix;
+      const candidates = [
+        path2.join(__dirname, "capabilities.json"),
+        path2.join(__dirname, "..", "capabilities.json")
+      ];
+      for (const candidate of candidates) {
+        try {
+          const json2 = require(candidate);
+          if (json2 && json2.charts) {
+            _capabilityMatrix = json2.charts;
+            _capabilityMatrixLoaded = true;
+            return _capabilityMatrix;
+          }
+        } catch {
+        }
+      }
+      _capabilityMatrixLoaded = true;
+      return _capabilityMatrix;
+    }
+    var CAPABILITY_KEY_MAP = {
+      push: "supportsPush",
+      linkedHover: "supportsLinkedHover",
+      ssr: "supportsSSR",
+      selection: "supportsSelection",
+      legend: "supportsLegend"
+    };
+    var VALID_CAPABILITY_KEYS = Object.keys(CAPABILITY_KEY_MAP);
+    function chartSatisfiesCapabilities(chartName, requirements) {
+      if (!requirements || Object.keys(requirements).length === 0) return true;
+      const matrix = loadCapabilityMatrix();
+      if (matrix == null) return false;
+      const spec = matrix[chartName];
+      if (!spec) return false;
+      for (const [shortKey, want] of Object.entries(requirements)) {
+        if (want == null) continue;
+        const matrixKey = CAPABILITY_KEY_MAP[shortKey];
+        if (!matrixKey) continue;
+        const has = spec[matrixKey] === true;
+        if (has !== want) return false;
+      }
+      return true;
+    }
+    function explainCapabilityMismatch(chartName, requirements) {
+      if (!requirements || Object.keys(requirements).length === 0) return null;
+      const matrix = loadCapabilityMatrix();
+      if (matrix == null) return "capability matrix unavailable (run `npm run docs:capabilities`)";
+      const spec = matrix[chartName];
+      if (!spec) return `${chartName} not found in capability matrix`;
+      const mismatches = [];
+      for (const [shortKey, want] of Object.entries(requirements)) {
+        if (want == null) continue;
+        const matrixKey = CAPABILITY_KEY_MAP[shortKey];
+        if (!matrixKey) continue;
+        const has = spec[matrixKey] === true;
+        if (has !== want) {
+          mismatches.push(`requires ${shortKey}=${want} but ${matrixKey}=${has}`);
+        }
+      }
+      return mismatches.length > 0 ? mismatches.join("; ") : null;
+    }
     function summarizeFields(data, keys) {
       const numericFields = [];
       const stringFields = [];
@@ -7003,16 +7156,38 @@ var require_chartSuggestions = __commonJS({
     function suggestCharts2(args = {}) {
       const data = args.data;
       const intent = args.intent;
+      const capabilities = args.capabilities;
       if (intent && !VALID_INTENTS.includes(intent)) {
         return {
           ok: false,
           error: `Unknown intent "${intent}". Expected one of: ${VALID_INTENTS.join(", ")}.`
         };
       }
+      if (capabilities) {
+        if (typeof capabilities !== "object" || Array.isArray(capabilities)) {
+          return {
+            ok: false,
+            error: "capabilities must be an object like { push: true, linkedHover: true, ssr: true, selection: true, legend: true }."
+          };
+        }
+        const unknown2 = Object.keys(capabilities).filter((k) => !VALID_CAPABILITY_KEYS.includes(k));
+        if (unknown2.length > 0) {
+          return {
+            ok: false,
+            error: `Unknown capability key(s): ${unknown2.join(", ")}. Expected: ${VALID_CAPABILITY_KEYS.join(", ")}.`
+          };
+        }
+        if (loadCapabilityMatrix() == null) {
+          return {
+            ok: false,
+            error: "Capability matrix unavailable: ai/capabilities.json is missing. Run `npm run docs:capabilities` to generate it. (Capability filtering requires the matrix; suggestions without a `capabilities` arg still work.)"
+          };
+        }
+      }
       if (!data || !Array.isArray(data) || data.length === 0) {
         return {
           ok: false,
-          error: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy'."
+          error: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy', or capabilities: { push, linkedHover, ssr, selection, legend }."
         };
       }
       if (data.length > MAX_SAMPLE_SIZE) {
@@ -7169,22 +7344,44 @@ var require_chartSuggestions = __commonJS({
           props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), valueAccessor: jsxString(valueField) }
         });
       }
+      const filteredSuggestions = capabilities ? suggestions.filter((s) => chartSatisfiesCapabilities(s.component, capabilities)) : suggestions;
       return {
         ok: true,
         intent,
+        capabilities,
         fieldSummary: `Fields: ${keys.join(", ")} (${numericFields.length} numeric, ${stringFields.length} categorical, ${dateFields.length} date)`,
         fields,
-        suggestions
+        suggestions: filteredSuggestions,
+        // Surface the pre-filter set when a capability constraint was
+        // applied — caller can see which suggestions were dropped and
+        // whether to relax the constraint.
+        ...capabilities && filteredSuggestions.length < suggestions.length && {
+          filteredOut: suggestions.filter((s) => !chartSatisfiesCapabilities(s.component, capabilities)).map((s) => ({
+            component: s.component,
+            // The `reason` here is the capability mismatch (which
+            // constraint failed), not the original data-shape rationale
+            // — callers debugging an empty result need to know which
+            // capability to relax, not why the chart was originally
+            // suggested.
+            reason: explainCapabilityMismatch(s.component, capabilities) || "did not satisfy capability constraints"
+          }))
+        }
       };
     }
     function formatSuggestionReport2(result) {
       if (!result.ok) return result.error;
       if (result.suggestions.length === 0) {
-        return `Could not confidently recommend a chart type.
+        const tail = result.capabilities && result.filteredOut && result.filteredOut.length > 0 ? `
+
+Dropped by capability filter (${formatCapabilityConstraints(result.capabilities)}):
+${result.filteredOut.map((s) => `- ${s.component}: ${s.reason}`).join("\n")}
 
-${result.fieldSummary}
+Relax the capability constraints, or use getSchema to browse alternatives.` : `
 
 Try providing intent ('${VALID_INTENTS.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`;
+        return `Could not confidently recommend a chart type.
+
+${result.fieldSummary}${tail}`;
       }
       const lines = result.suggestions.map((suggestion, i) => {
         const propsStr = Object.entries(suggestion.props).map(([k, v]) => `${k}=${v}`).join(" ");
@@ -7216,10 +7413,18 @@ Or use \`<ThemeProvider theme="dark">\` / \`<ThemeProvider theme={{ colors: {...
 For accessibility, use \`colorScheme={COLOR_BLIND_SAFE_CATEGORICAL}\` (import from \`semiotic/themes\`) - 8-color palette safe for all forms of color blindness.`;
       return lines.join("\n\n") + themingTip;
     }
+    function formatCapabilityConstraints(capabilities) {
+      return Object.entries(capabilities).filter(([, v]) => v != null).map(([k, v]) => `${k}=${v}`).join(", ");
+    }
     module2.exports = {
       VALID_INTENTS,
+      VALID_CAPABILITY_KEYS,
       formatSuggestionReport: formatSuggestionReport2,
-      suggestCharts: suggestCharts2
+      suggestCharts: suggestCharts2,
+      // Exported for tests + callers that want to filter their own
+      // chart-name set without re-running the suggestion pipeline.
+      chartSatisfiesCapabilities,
+      explainCapabilityMismatch
     };
   }
 });
@@ -32147,6 +32352,7 @@ var import_geo = require("semiotic/geo");
 var COMPONENT_REGISTRY = {
   LineChart: { component: import_ai.LineChart, category: "xy" },
   AreaChart: { component: import_ai.AreaChart, category: "xy" },
+  DifferenceChart: { component: import_ai.DifferenceChart, category: "xy" },
   StackedAreaChart: { component: import_ai.StackedAreaChart, category: "xy" },
   Scatterplot: { component: import_ai.Scatterplot, category: "xy" },
   BubbleChart: { component: import_ai.BubbleChart, category: "xy" },
@@ -32175,6 +32381,7 @@ var COMPONENT_REGISTRY = {
   ForceDirectedGraph: { component: import_ai.ForceDirectedGraph, category: "network" },
   ChordDiagram: { component: import_ai.ChordDiagram, category: "network" },
   SankeyDiagram: { component: import_ai.SankeyDiagram, category: "network" },
+  ProcessSankey: { component: import_ai.ProcessSankey, category: "network" },
   TreeDiagram: { component: import_ai.TreeDiagram, category: "network" },
   Treemap: { component: import_ai.Treemap, category: "network" },
   CirclePack: { component: import_ai.CirclePack, category: "network" },
@@ -32660,10 +32867,21 @@ function createServer2() {
   );
   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.",
+    "Recommend Semiotic chart types for a given data sample. Pass { data: [...] } with 1-5 sample objects. Optionally pass intent to narrow suggestions, or capabilities to require/forbid features (push API, linked hover, SSR, selection, legend). Returns ranked recommendations with example props; charts that don't satisfy the capability constraints are dropped.",
     {
       data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).min(1).max(5).describe("1-5 sample data objects"),
-      intent: external_exports3.enum(["comparison", "trend", "distribution", "relationship", "composition", "geographic", "network", "hierarchy"]).optional().describe("Visualization intent to narrow suggestions")
+      intent: external_exports3.enum(["comparison", "trend", "distribution", "relationship", "composition", "geographic", "network", "hierarchy"]).optional().describe("Visualization intent to narrow suggestions"),
+      capabilities: external_exports3.object({
+        push: external_exports3.boolean().optional().describe("Require ref-based push API (live streaming via ref.current.push())"),
+        linkedHover: external_exports3.boolean().optional().describe("Require cross-chart linked hover support"),
+        ssr: external_exports3.boolean().optional().describe("Require server-side rendering via renderChart()"),
+        selection: external_exports3.boolean().optional().describe("Require named selection / cross-filter support"),
+        legend: external_exports3.boolean().optional().describe("Require a top-level legend")
+        // `.strict()` so the MCP surface rejects unknown capability
+        // keys at the schema layer rather than silently stripping
+        // them — keeps the cjs-level "Unknown capability key(s)"
+        // validation from being unreachable from MCP callers.
+      }).strict().optional().describe("Capability constraints \u2014 set a key to true to require, false to forbid. Unset keys are ignored.")
     },
     suggestChartHandler
   );

package/ai/examples.md

@@ -199,6 +199,42 @@ const data = [
 
 Key props: `y0Accessor` defines band bottom, `yAccessor` defines band top, `showLine={false}` hides the top edge stroke. Layer a `LineChart` on top for the main metric.
 
+### DifferenceChart
+
+```jsx
+import { DifferenceChart } from "semiotic/ai"
+
+const tempData = [
+  { month: 1,  actual: 38, normal: 32 },
+  { month: 2,  actual: 41, normal: 36 },
+  { month: 3,  actual: 45, normal: 48 },
+  { month: 4,  actual: 55, normal: 57 },
+  { month: 5,  actual: 61, normal: 66 },
+  { month: 6,  actual: 70, normal: 75 },
+  { month: 7,  actual: 79, normal: 79 },
+  { month: 8,  actual: 81, normal: 78 },
+  { month: 9,  actual: 74, normal: 70 },
+  { month: 10, actual: 64, normal: 58 },
+  { month: 11, actual: 52, normal: 47 },
+  { month: 12, actual: 42, normal: 37 }
+]
+
+<DifferenceChart
+  data={tempData}
+  xAccessor="month"
+  seriesAAccessor="actual"
+  seriesBAccessor="normal"
+  seriesALabel="Actual"
+  seriesBLabel="Normal"
+  xLabel="Month"
+  yLabel="°F"
+/>
+```
+
+Fills the region between two series with a color that switches based on which series is higher at each x — `seriesAColor` where A > B, `seriesBColor` where B > A. Crossover x-values are linearly interpolated so adjacent segments meet at zero-width vertices (no jagged seams). Classic uses: temperature anomaly, forecast vs. actual, budget variance, any A/B comparison.
+
+Key props: `seriesALabel` / `seriesBLabel` (legend + tooltip), `seriesAColor` / `seriesBColor` (defaults to `var(--semiotic-danger)` / `var(--semiotic-info)`), `showLines` (default `true` — draws both series on top of the fill), `areaOpacity` (0.6), `gradientFill` (same shape as AreaChart), `windowSize` (max raw rows in push buffer; FIFO eviction). Push API: `ref.current.push({ x, a, b })` — accessor outputs coerce through a `toNumber` helper so `Date` (time series) and numeric strings (CSV/JSON) work transparently.
+
 ### StackedAreaChart
 
 ```jsx
@@ -661,6 +697,38 @@ const edges = [
 
 Key props: **`edges`** (required, nodes inferred), `valueAccessor` controls band width
 
+### ProcessSankey
+
+```jsx
+import { ProcessSankey } from "semiotic/ai"
+
+const nodes = [
+  { id: "Alice", category: "Person", xExtent: ["2026-01-06", "2026-01-06"] },
+  { id: "Bob",   category: "Person", xExtent: ["2026-02-01", "2026-02-01"] },
+  { id: "Eng",     category: "Team" },
+  { id: "Release", category: "Milestone", xExtent: ["2026-04-15", "2026-05-30"] },
+]
+
+const edges = [
+  { id: "alice-eng", source: "Alice", target: "Eng", value: 8,
+    startTime: "2026-01-20", endTime: "2026-02-10" },
+  { id: "bob-eng",   source: "Bob",   target: "Eng", value: 5,
+    startTime: "2026-02-15", endTime: "2026-03-15" },
+  { id: "eng-rel",   source: "Eng",   target: "Release", value: 13,
+    startTime: "2026-04-15", endTime: "2026-05-15" },
+]
+
+<ProcessSankey
+  nodes={nodes}
+  edges={edges}
+  domain={["2026-01-01", "2026-05-31"]}
+  colorBy="category"
+  showLegend
+/>
+```
+
+Key props: **`edges`** with `startTime`/`endTime`, **`domain`** (required `[t0, t1]`); nodes optionally carry `xExtent: [start, end]` to bound the lane (`min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`). Use when flow events have timestamps; use SankeyDiagram for static total-flow snapshots.
+
 ### ChordDiagram
 
 ```jsx