@zendir/ui 0.2.21 → 0.3.1

package/dist/react/charts/unified/useChartStream.js

@@ -0,0 +1,226 @@
+import { useRef, useState, useCallback, useEffect } from "react";
+function useChartStream(chartRef, options = {}) {
+  const {
+    maxPoints: _maxPoints = 1e3,
+    timeWindow: _timeWindow,
+    throttleMs = 16,
+    // ~60fps
+    bufferSize = 10,
+    decimate = true,
+    decimateThreshold = 5e3
+  } = options;
+  const bufferRef = useRef(/* @__PURE__ */ new Map());
+  const lastFlushRef = useRef(0);
+  const pointCountRef = useRef(0);
+  const [isPaused, setIsPaused] = useState(false);
+  const animationFrameRef = useRef();
+  const flush = useCallback(() => {
+    const chart = chartRef.current;
+    if (!chart || isPaused) return;
+    const now = Date.now();
+    if (now - lastFlushRef.current < throttleMs) {
+      animationFrameRef.current = requestAnimationFrame(flush);
+      return;
+    }
+    bufferRef.current.forEach((points, seriesIndex) => {
+      if (points.length === 0) return;
+      let processedPoints = points;
+      if (decimate && pointCountRef.current > decimateThreshold) {
+        processedPoints = decimateData(points, Math.ceil(points.length / 2));
+      }
+      processedPoints.forEach((point) => {
+        chart.appendData(seriesIndex, point);
+      });
+      pointCountRef.current += processedPoints.length;
+    });
+    bufferRef.current.clear();
+    lastFlushRef.current = now;
+  }, [chartRef, isPaused, throttleMs, decimate, decimateThreshold]);
+  const push = useCallback((seriesIndex, point) => {
+    if (isPaused) return;
+    let buffer = bufferRef.current.get(seriesIndex);
+    if (!buffer) {
+      buffer = [];
+      bufferRef.current.set(seriesIndex, buffer);
+    }
+    buffer.push(point);
+    if (buffer.length >= bufferSize) {
+      flush();
+    } else if (!animationFrameRef.current) {
+      animationFrameRef.current = requestAnimationFrame(() => {
+        animationFrameRef.current = void 0;
+        flush();
+      });
+    }
+  }, [isPaused, bufferSize, flush]);
+  const pushBatch = useCallback((seriesIndex, points) => {
+    if (isPaused || points.length === 0) return;
+    let buffer = bufferRef.current.get(seriesIndex);
+    if (!buffer) {
+      buffer = [];
+      bufferRef.current.set(seriesIndex, buffer);
+    }
+    buffer.push(...points);
+    flush();
+  }, [isPaused, flush]);
+  const clear = useCallback(() => {
+    var _a;
+    bufferRef.current.clear();
+    pointCountRef.current = 0;
+    (_a = chartRef.current) == null ? void 0 : _a.clearData();
+  }, [chartRef]);
+  const pause = useCallback(() => setIsPaused(true), []);
+  const resume = useCallback(() => setIsPaused(false), []);
+  useEffect(() => {
+    return () => {
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current);
+      }
+    };
+  }, []);
+  return {
+    push,
+    pushBatch,
+    clear,
+    pause,
+    resume,
+    isPaused,
+    pointCount: pointCountRef.current
+  };
+}
+function decimateData(data, threshold) {
+  if (data.length <= threshold) return data;
+  const result = [];
+  const bucketSize = (data.length - 2) / (threshold - 2);
+  result.push(data[0]);
+  let a = 0;
+  for (let i = 0; i < threshold - 2; i++) {
+    const bucketStart = Math.floor((i + 1) * bucketSize) + 1;
+    const bucketEnd = Math.floor((i + 2) * bucketSize) + 1;
+    const bucketLength = Math.min(bucketEnd, data.length) - bucketStart;
+    let avgX = 0;
+    let avgY = 0;
+    const nextBucketStart = Math.floor((i + 2) * bucketSize) + 1;
+    const nextBucketEnd = Math.min(Math.floor((i + 3) * bucketSize) + 1, data.length);
+    const nextBucketLength = nextBucketEnd - nextBucketStart;
+    for (let j = nextBucketStart; j < nextBucketEnd; j++) {
+      const point = data[j];
+      const [x, y] = getPointXY(point);
+      avgX += x;
+      avgY += y;
+    }
+    avgX /= nextBucketLength || 1;
+    avgY /= nextBucketLength || 1;
+    const [aX, aY] = getPointXY(data[a]);
+    let maxArea = -1;
+    let maxIdx = bucketStart;
+    for (let j = bucketStart; j < bucketStart + bucketLength; j++) {
+      const point = data[j];
+      const [x, y] = getPointXY(point);
+      const area = Math.abs(
+        (aX - avgX) * (y - aY) - (aX - x) * (avgY - aY)
+      );
+      if (area > maxArea) {
+        maxArea = area;
+        maxIdx = j;
+      }
+    }
+    result.push(data[maxIdx]);
+    a = maxIdx;
+  }
+  result.push(data[data.length - 1]);
+  return result;
+}
+function getPointXY(point) {
+  if ("time" in point) {
+    return [
+      typeof point.time === "number" ? point.time : new Date(point.time).getTime(),
+      point.value
+    ];
+  }
+  return [
+    typeof point.x === "number" ? point.x : 0,
+    point.y
+  ];
+}
+function useWebSocketStream(chartRef, options) {
+  const {
+    url,
+    reconnect = true,
+    reconnectDelay = 1e3,
+    maxReconnects = 10,
+    parseMessage,
+    ...streamOptions
+  } = options;
+  const wsRef = useRef(null);
+  const reconnectCountRef = useRef(0);
+  const reconnectTimerRef = useRef();
+  const [connectionState, setConnectionState] = useState("disconnected");
+  const stream = useChartStream(chartRef, streamOptions);
+  const connect = useCallback(() => {
+    var _a;
+    if (((_a = wsRef.current) == null ? void 0 : _a.readyState) === WebSocket.OPEN) return;
+    setConnectionState("connecting");
+    const ws = new WebSocket(url);
+    ws.onopen = () => {
+      setConnectionState("connected");
+      reconnectCountRef.current = 0;
+    };
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        const parsed = parseMessage ? parseMessage(data) : defaultParseMessage(data);
+        if (parsed) {
+          stream.push(parsed.seriesIndex, parsed.point);
+        }
+      } catch (e) {
+      }
+    };
+    ws.onerror = () => {
+      setConnectionState("error");
+    };
+    ws.onclose = () => {
+      setConnectionState("disconnected");
+      if (reconnect && reconnectCountRef.current < maxReconnects) {
+        reconnectCountRef.current++;
+        reconnectTimerRef.current = setTimeout(connect, reconnectDelay * reconnectCountRef.current);
+      }
+    };
+    wsRef.current = ws;
+  }, [url, reconnect, reconnectDelay, maxReconnects, parseMessage, stream]);
+  const disconnect = useCallback(() => {
+    var _a;
+    clearTimeout(reconnectTimerRef.current);
+    (_a = wsRef.current) == null ? void 0 : _a.close();
+    wsRef.current = null;
+  }, []);
+  useEffect(() => {
+    connect();
+    return disconnect;
+  }, [connect, disconnect]);
+  return {
+    ...stream,
+    connectionState,
+    connect,
+    disconnect
+  };
+}
+function defaultParseMessage(data) {
+  if (typeof data !== "object" || data === null) return null;
+  const obj = data;
+  if ("time" in obj && "value" in obj) {
+    return {
+      seriesIndex: typeof obj.seriesIndex === "number" ? obj.seriesIndex : 0,
+      point: {
+        time: obj.time,
+        value: obj.value
+      }
+    };
+  }
+  return null;
+}
+export {
+  useChartStream,
+  useWebSocketStream
+};
+//# sourceMappingURL=useChartStream.js.map

package/dist/react/charts/unified/useChartStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartStream.js","sources":["../../../../src/react/charts/unified/useChartStream.ts"],"sourcesContent":["/**\n * @zendir/ui - Real-time Chart Streaming Hook\n * \n * Provides efficient real-time data streaming for charts.\n * Handles buffering, throttling, and memory management.\n */\n\nimport { useRef, useCallback, useEffect, useState } from 'react';\nimport type { AstroChartHandle } from './AstroChart';\nimport type { TimeSeriesPoint, DataPoint } from './types';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface StreamOptions {\n  /** Maximum data points to keep */\n  maxPoints?: number;\n  /** Time window in milliseconds (alternative to maxPoints) */\n  timeWindow?: number;\n  /** Throttle interval in milliseconds */\n  throttleMs?: number;\n  /** Buffer size before flushing */\n  bufferSize?: number;\n  /** Enable data decimation for large datasets */\n  decimate?: boolean;\n  /** Decimation threshold (start decimating above this count) */\n  decimateThreshold?: number;\n}\n\nexport interface StreamController {\n  /** Push a single data point */\n  push: (seriesIndex: number, point: TimeSeriesPoint | DataPoint) => void;\n  /** Push multiple data points */\n  pushBatch: (seriesIndex: number, points: (TimeSeriesPoint | DataPoint)[]) => void;\n  /** Clear all data */\n  clear: () => void;\n  /** Pause streaming */\n  pause: () => void;\n  /** Resume streaming */\n  resume: () => void;\n  /** Get current state */\n  isPaused: boolean;\n  /** Get current point count */\n  pointCount: number;\n}\n\n// =============================================================================\n// Hook Implementation\n// =============================================================================\n\nexport function useChartStream(\n  chartRef: React.RefObject<AstroChartHandle>,\n  options: StreamOptions = {}\n): StreamController {\n  const {\n    maxPoints: _maxPoints = 1000,\n    timeWindow: _timeWindow,\n    throttleMs = 16, // ~60fps\n    bufferSize = 10,\n    decimate = true,\n    decimateThreshold = 5000,\n  } = options;\n\n  const bufferRef = useRef<Map<number, (TimeSeriesPoint | DataPoint)[]>>(new Map());\n  const lastFlushRef = useRef<number>(0);\n  const pointCountRef = useRef<number>(0);\n  const [isPaused, setIsPaused] = useState(false);\n  const animationFrameRef = useRef<number>();\n\n  // Flush buffer to chart\n  const flush = useCallback(() => {\n    const chart = chartRef.current;\n    if (!chart || isPaused) return;\n\n    const now = Date.now();\n    if (now - lastFlushRef.current < throttleMs) {\n      // Schedule next flush\n      animationFrameRef.current = requestAnimationFrame(flush);\n      return;\n    }\n\n    bufferRef.current.forEach((points, seriesIndex) => {\n      if (points.length === 0) return;\n\n      // Apply decimation if needed\n      let processedPoints = points;\n      if (decimate && pointCountRef.current > decimateThreshold) {\n        processedPoints = decimateData(points, Math.ceil(points.length / 2));\n      }\n\n      // Append each point\n      processedPoints.forEach(point => {\n        chart.appendData(seriesIndex, point);\n      });\n\n      pointCountRef.current += processedPoints.length;\n    });\n\n    // Clear buffer\n    bufferRef.current.clear();\n    lastFlushRef.current = now;\n  }, [chartRef, isPaused, throttleMs, decimate, decimateThreshold]);\n\n  // Push single point\n  const push = useCallback((seriesIndex: number, point: TimeSeriesPoint | DataPoint) => {\n    if (isPaused) return;\n\n    let buffer = bufferRef.current.get(seriesIndex);\n    if (!buffer) {\n      buffer = [];\n      bufferRef.current.set(seriesIndex, buffer);\n    }\n\n    buffer.push(point);\n\n    // Flush if buffer is full\n    if (buffer.length >= bufferSize) {\n      flush();\n    } else if (!animationFrameRef.current) {\n      // Schedule flush\n      animationFrameRef.current = requestAnimationFrame(() => {\n        animationFrameRef.current = undefined;\n        flush();\n      });\n    }\n  }, [isPaused, bufferSize, flush]);\n\n  // Push batch\n  const pushBatch = useCallback((seriesIndex: number, points: (TimeSeriesPoint | DataPoint)[]) => {\n    if (isPaused || points.length === 0) return;\n\n    let buffer = bufferRef.current.get(seriesIndex);\n    if (!buffer) {\n      buffer = [];\n      bufferRef.current.set(seriesIndex, buffer);\n    }\n\n    buffer.push(...points);\n    flush();\n  }, [isPaused, flush]);\n\n  // Clear all data\n  const clear = useCallback(() => {\n    bufferRef.current.clear();\n    pointCountRef.current = 0;\n    chartRef.current?.clearData();\n  }, [chartRef]);\n\n  // Pause/resume\n  const pause = useCallback(() => setIsPaused(true), []);\n  const resume = useCallback(() => setIsPaused(false), []);\n\n  // Cleanup\n  useEffect(() => {\n    return () => {\n      if (animationFrameRef.current) {\n        cancelAnimationFrame(animationFrameRef.current);\n      }\n    };\n  }, []);\n\n  return {\n    push,\n    pushBatch,\n    clear,\n    pause,\n    resume,\n    isPaused,\n    pointCount: pointCountRef.current,\n  };\n}\n\n// =============================================================================\n// Data Decimation\n// =============================================================================\n\n/**\n * Largest Triangle Three Buckets (LTTB) algorithm for data decimation\n * Preserves visual shape while reducing point count\n */\nfunction decimateData<T extends TimeSeriesPoint | DataPoint>(\n  data: T[],\n  threshold: number\n): T[] {\n  if (data.length <= threshold) return data;\n\n  const result: T[] = [];\n  const bucketSize = (data.length - 2) / (threshold - 2);\n\n  // Always include first point\n  result.push(data[0]);\n\n  let a = 0; // Previous selected point\n\n  for (let i = 0; i < threshold - 2; i++) {\n    // Calculate bucket range\n    const bucketStart = Math.floor((i + 1) * bucketSize) + 1;\n    const bucketEnd = Math.floor((i + 2) * bucketSize) + 1;\n    const bucketLength = Math.min(bucketEnd, data.length) - bucketStart;\n\n    // Calculate average point in next bucket\n    let avgX = 0;\n    let avgY = 0;\n    const nextBucketStart = Math.floor((i + 2) * bucketSize) + 1;\n    const nextBucketEnd = Math.min(Math.floor((i + 3) * bucketSize) + 1, data.length);\n    const nextBucketLength = nextBucketEnd - nextBucketStart;\n\n    for (let j = nextBucketStart; j < nextBucketEnd; j++) {\n      const point = data[j];\n      const [x, y] = getPointXY(point);\n      avgX += x;\n      avgY += y;\n    }\n    avgX /= nextBucketLength || 1;\n    avgY /= nextBucketLength || 1;\n\n    // Find point with largest triangle area\n    const [aX, aY] = getPointXY(data[a]);\n    let maxArea = -1;\n    let maxIdx = bucketStart;\n\n    for (let j = bucketStart; j < bucketStart + bucketLength; j++) {\n      const point = data[j];\n      const [x, y] = getPointXY(point);\n      \n      // Triangle area\n      const area = Math.abs(\n        (aX - avgX) * (y - aY) - (aX - x) * (avgY - aY)\n      );\n\n      if (area > maxArea) {\n        maxArea = area;\n        maxIdx = j;\n      }\n    }\n\n    result.push(data[maxIdx]);\n    a = maxIdx;\n  }\n\n  // Always include last point\n  result.push(data[data.length - 1]);\n\n  return result;\n}\n\nfunction getPointXY(point: TimeSeriesPoint | DataPoint): [number, number] {\n  if ('time' in point) {\n    return [\n      typeof point.time === 'number' ? point.time : new Date(point.time).getTime(),\n      point.value,\n    ];\n  }\n  return [\n    typeof point.x === 'number' ? point.x : 0,\n    point.y,\n  ];\n}\n\n// =============================================================================\n// WebSocket Stream Hook\n// =============================================================================\n\nexport interface WebSocketStreamOptions extends StreamOptions {\n  /** WebSocket URL */\n  url: string;\n  /** Reconnect on disconnect */\n  reconnect?: boolean;\n  /** Reconnect delay in milliseconds */\n  reconnectDelay?: number;\n  /** Maximum reconnect attempts */\n  maxReconnects?: number;\n  /** Message parser */\n  parseMessage?: (data: unknown) => { seriesIndex: number; point: TimeSeriesPoint | DataPoint } | null;\n}\n\nexport interface WebSocketStreamController extends StreamController {\n  /** WebSocket connection state */\n  connectionState: 'connecting' | 'connected' | 'disconnected' | 'error';\n  /** Manually connect */\n  connect: () => void;\n  /** Manually disconnect */\n  disconnect: () => void;\n}\n\nexport function useWebSocketStream(\n  chartRef: React.RefObject<AstroChartHandle>,\n  options: WebSocketStreamOptions\n): WebSocketStreamController {\n  const {\n    url,\n    reconnect = true,\n    reconnectDelay = 1000,\n    maxReconnects = 10,\n    parseMessage,\n    ...streamOptions\n  } = options;\n\n  const wsRef = useRef<WebSocket | null>(null);\n  const reconnectCountRef = useRef(0);\n  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout>>();\n  const [connectionState, setConnectionState] = useState<WebSocketStreamController['connectionState']>('disconnected');\n  \n  const stream = useChartStream(chartRef, streamOptions);\n\n  const connect = useCallback(() => {\n    if (wsRef.current?.readyState === WebSocket.OPEN) return;\n\n    setConnectionState('connecting');\n    const ws = new WebSocket(url);\n\n    ws.onopen = () => {\n      setConnectionState('connected');\n      reconnectCountRef.current = 0;\n    };\n\n    ws.onmessage = (event) => {\n      try {\n        const data = JSON.parse(event.data);\n        const parsed = parseMessage \n          ? parseMessage(data) \n          : defaultParseMessage(data);\n        \n        if (parsed) {\n          stream.push(parsed.seriesIndex, parsed.point);\n        }\n      } catch (e) {\n        if (import.meta.env.DEV) {\n          console.error('Failed to parse WebSocket message:', e);\n        }\n      }\n    };\n\n    ws.onerror = () => {\n      setConnectionState('error');\n    };\n\n    ws.onclose = () => {\n      setConnectionState('disconnected');\n      \n      if (reconnect && reconnectCountRef.current < maxReconnects) {\n        reconnectCountRef.current++;\n        reconnectTimerRef.current = setTimeout(connect, reconnectDelay * reconnectCountRef.current);\n      }\n    };\n\n    wsRef.current = ws;\n  }, [url, reconnect, reconnectDelay, maxReconnects, parseMessage, stream]);\n\n  const disconnect = useCallback(() => {\n    clearTimeout(reconnectTimerRef.current);\n    wsRef.current?.close();\n    wsRef.current = null;\n  }, []);\n\n  // Auto-connect on mount\n  useEffect(() => {\n    connect();\n    return disconnect;\n  }, [connect, disconnect]);\n\n  return {\n    ...stream,\n    connectionState,\n    connect,\n    disconnect,\n  };\n}\n\nfunction defaultParseMessage(data: unknown): { seriesIndex: number; point: TimeSeriesPoint } | null {\n  if (typeof data !== 'object' || data === null) return null;\n  \n  const obj = data as Record<string, unknown>;\n  \n  if ('time' in obj && 'value' in obj) {\n    return {\n      seriesIndex: typeof obj.seriesIndex === 'number' ? obj.seriesIndex : 0,\n      point: {\n        time: obj.time as number,\n        value: obj.value as number,\n      },\n    };\n  }\n  \n  return null;\n}\n"],"names":[],"mappings":"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"}

package/dist/react/chatgpt/AppCard.d.ts

@@ -52,8 +52,4 @@ export interface AppCardProps {
  * crash the host application — critical for sandboxed iframes.
  */
 export declare const AppCard: React.FC<AppCardProps>;
-/** @deprecated Use `AppCard` instead. Alias kept for backward compatibility. */
-export declare const ChatGPTCard: React.FC<AppCardProps>;
-/** @deprecated Use `AppCardProps` instead. */
-export type ChatGPTCardProps = AppCardProps;
 export default AppCard;

package/dist/react/chatgpt/index.d.ts

@@ -130,25 +130,6 @@ export declare function useCallTool(): {
  * Send a follow-up message as if the user asked it
  */
 export declare function useSendMessage(): (prompt: string) => Promise<void>;
-/**
- * DEPRECATED: Do not use notifyIntrinsicHeight!
- *
- * According to OpenAI Apps SDK examples (via DeepWiki), the correct pattern is:
- * - The HOST provides maxHeight via window.openai.maxHeight
- * - Widgets READ this and constrain themselves
- * - Widgets NEVER report height back to the host
- *
- * Calling notifyIntrinsicHeight causes infinite resize loops in MCPJam sandbox
- * because the sandbox responds by resizing the container, which triggers another
- * resize event.
- *
- * Use useMaxHeight() instead to get the host's height constraint.
- *
- * @deprecated Use useMaxHeight() instead
- */
-export declare function useIntrinsicHeight(_ref: {
-    current: HTMLElement | null;
-}): void;
 /**
  * Get the maximum height available for the widget from the host environment.
  * This is the CORRECT pattern per OpenAI Apps SDK examples.

package/dist/react/chatgpt/index.js

@@ -0,0 +1,163 @@
+import { useState, useCallback, useEffect, useSyncExternalStore } from "react";
+const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+function useOpenAiGlobal(key) {
+  const getSnapshot = useCallback(() => {
+    var _a;
+    return (_a = window.openai) == null ? void 0 : _a[key];
+  }, [key]);
+  const subscribe = useCallback((onChange) => {
+    const handleSetGlobal = (event) => {
+      var _a, _b;
+      const customEvent = event;
+      if (((_b = (_a = customEvent.detail) == null ? void 0 : _a.globals) == null ? void 0 : _b[key]) !== void 0) {
+        onChange();
+      }
+    };
+    window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, { passive: true });
+    return () => window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
+  }, [key]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function useWidgetState(defaultState) {
+  const widgetStateFromWindow = useOpenAiGlobal("widgetState");
+  const [widgetState, _setWidgetState] = useState(() => {
+    if (widgetStateFromWindow != null) {
+      return widgetStateFromWindow;
+    }
+    return typeof defaultState === "function" ? defaultState() : defaultState;
+  });
+  useEffect(() => {
+    if (widgetStateFromWindow != null) {
+      _setWidgetState(widgetStateFromWindow);
+    }
+  }, [widgetStateFromWindow]);
+  const setWidgetState = useCallback((state) => {
+    _setWidgetState((prevState) => {
+      var _a, _b;
+      const newState = typeof state === "function" ? state(prevState) : state;
+      (_b = (_a = window.openai) == null ? void 0 : _a.setWidgetState) == null ? void 0 : _b.call(_a, newState);
+      return newState;
+    });
+  }, []);
+  return [widgetState, setWidgetState];
+}
+function useToolOutput() {
+  return useOpenAiGlobal("toolOutput");
+}
+function useToolInput() {
+  return useOpenAiGlobal("toolInput");
+}
+function useChatGPTTheme() {
+  const theme = useOpenAiGlobal("theme") ?? "dark";
+  const isDark = theme === "dark";
+  return {
+    theme,
+    isDark,
+    colors: isDark ? {
+      background: "#09090b",
+      surface: "#18181b",
+      surfaceHover: "#27272a",
+      border: "#3f3f46",
+      text: "#fafafa",
+      textMuted: "#a1a1aa",
+      accent: "#22d3ee"
+    } : {
+      background: "#ffffff",
+      surface: "#f4f4f5",
+      surfaceHover: "#e4e4e7",
+      border: "#d4d4d8",
+      text: "#18181b",
+      textMuted: "#636370",
+      // WCAG AA: 5.90:1 on #fff, 5.39:1 on #f4f4f5, 4.66:1 on #e4e4e7 (was #71717a → 4.49:1 FAIL on surface)
+      accent: "#0ea5e9"
+    }
+  };
+}
+function useLocale() {
+  return useOpenAiGlobal("locale") ?? "en-US";
+}
+function useDisplayMode() {
+  const mode = useOpenAiGlobal("displayMode") ?? "inline";
+  const maxHeight = useOpenAiGlobal("maxHeight");
+  const requestMode = useCallback(async (newMode) => {
+    var _a, _b;
+    await ((_b = (_a = window.openai) == null ? void 0 : _a.requestDisplayMode) == null ? void 0 : _b.call(_a, { mode: newMode }));
+  }, []);
+  const close = useCallback(() => {
+    var _a, _b;
+    (_b = (_a = window.openai) == null ? void 0 : _a.requestClose) == null ? void 0 : _b.call(_a);
+  }, []);
+  return { mode, maxHeight, requestMode, close };
+}
+function useCallTool() {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const callTool = useCallback(async (name, args) => {
+    var _a;
+    if (!((_a = window.openai) == null ? void 0 : _a.callTool)) {
+      throw new Error("window.openai.callTool not available");
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await window.openai.callTool(name, args);
+      return result;
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error(String(err));
+      setError(error2);
+      throw error2;
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+  return { callTool, isLoading, error };
+}
+function useSendMessage() {
+  return useCallback(async (prompt) => {
+    var _a, _b;
+    await ((_b = (_a = window.openai) == null ? void 0 : _a.sendFollowUpMessage) == null ? void 0 : _b.call(_a, { prompt }));
+  }, []);
+}
+function useMaxHeight() {
+  const [maxHeight, setMaxHeight] = useState(
+    () => {
+      var _a;
+      return (_a = window.openai) == null ? void 0 : _a.maxHeight;
+    }
+  );
+  useEffect(() => {
+    const handler = (event) => {
+      var _a;
+      if (((_a = event.detail) == null ? void 0 : _a.globals) && "maxHeight" in event.detail.globals) {
+        setMaxHeight(event.detail.globals.maxHeight);
+      }
+    };
+    window.addEventListener("openai:set_globals", handler);
+    return () => window.removeEventListener("openai:set_globals", handler);
+  }, []);
+  return maxHeight;
+}
+function useOpenExternal() {
+  return useCallback((href) => {
+    var _a, _b;
+    (_b = (_a = window.openai) == null ? void 0 : _a.openExternal) == null ? void 0 : _b.call(_a, { href });
+  }, []);
+}
+function isInChatGPT() {
+  return typeof window !== "undefined" && window.openai !== void 0;
+}
+export {
+  isInChatGPT,
+  useCallTool,
+  useChatGPTTheme,
+  useDisplayMode,
+  useLocale,
+  useMaxHeight,
+  useOpenAiGlobal,
+  useOpenExternal,
+  useSendMessage,
+  useToolInput,
+  useToolOutput,
+  useWidgetState
+};
+//# sourceMappingURL=index.js.map

package/dist/react/chatgpt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/react/chatgpt/index.ts"],"sourcesContent":["/**\n * ChatGPT Apps SDK Integration\n * \n * Hooks and utilities for integrating Zendir UI components with ChatGPT's\n * window.openai API. Based on: https://developers.openai.com/apps-sdk/build/chatgpt-ui/\n * \n * Key capabilities:\n * - window.openai.toolInput / toolOutput - Tool data from MCP server\n * - window.openai.widgetState / setWidgetState - Persistent UI state\n * - window.openai.callTool - Invoke other MCP tools from widget\n * - window.openai.sendFollowUpMessage - Insert user messages\n * - window.openai.theme - Light/dark theme detection\n * - window.openai.locale - Localization\n * - window.openai.requestDisplayMode - Fullscreen/PiP modes\n * - window.openai.notifyIntrinsicHeight - Dynamic height reporting\n */\n\nimport { useState, useEffect, useCallback, useSyncExternalStore } from 'react';\n\n// ============================================================================\n// Type Definitions\n// ============================================================================\n\nexport interface OpenAiGlobals {\n  /** Arguments supplied when the tool was invoked */\n  toolInput?: Record<string, unknown>;\n  /** Your structuredContent - the model reads this */\n  toolOutput?: Record<string, unknown>;\n  /** Metadata payload - only widget sees it */\n  toolResponseMetadata?: Record<string, unknown>;\n  /** Snapshot of UI state persisted between renders */\n  widgetState?: Record<string, unknown>;\n  /** Current theme */\n  theme?: 'light' | 'dark';\n  /** Current locale (e.g., 'en-US') */\n  locale?: string;\n  /** Display mode */\n  displayMode?: 'inline' | 'pip' | 'fullscreen';\n  /** Maximum allowed height */\n  maxHeight?: number;\n  /** View type */\n  view?: 'conversation' | 'modal';\n  /** User agent info */\n  userAgent?: string;\n  /** Safe area insets */\n  safeArea?: { top: number; bottom: number; left: number; right: number };\n  \n  // API Methods\n  setWidgetState?: (state: Record<string, unknown>) => void;\n  callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;\n  sendFollowUpMessage?: (options: { prompt: string }) => Promise<void>;\n  uploadFile?: (file: File) => Promise<{ fileId: string }>;\n  getFileDownloadUrl?: (options: { fileId: string }) => Promise<{ downloadUrl: string }>;\n  requestDisplayMode?: (options: { mode: 'inline' | 'pip' | 'fullscreen' }) => Promise<void>;\n  requestModal?: (options: unknown) => Promise<void>;\n  notifyIntrinsicHeight?: (height: number) => void;\n  openExternal?: (options: { href: string }) => void;\n  requestClose?: () => void;\n}\n\ndeclare global {\n  interface Window {\n    openai?: OpenAiGlobals;\n  }\n}\n\n// ============================================================================\n// Core Hook: useOpenAiGlobal\n// ============================================================================\n\nconst SET_GLOBALS_EVENT_TYPE = 'openai:set_globals';\n\ninterface SetGlobalsEvent extends CustomEvent {\n  detail: { globals: Partial<OpenAiGlobals> };\n}\n\n/**\n * Subscribe to a specific window.openai global value\n */\nexport function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] {\n  const getSnapshot = useCallback(() => {\n    return window.openai?.[key];\n  }, [key]);\n\n  const subscribe = useCallback((onChange: () => void) => {\n    const handleSetGlobal = (event: Event) => {\n      const customEvent = event as SetGlobalsEvent;\n      if (customEvent.detail?.globals?.[key] !== undefined) {\n        onChange();\n      }\n    };\n\n    window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, { passive: true });\n    return () => window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);\n  }, [key]);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n// ============================================================================\n// Widget State Hook\n// ============================================================================\n\ntype SetStateAction<T> = T | ((prevState: T) => T);\n\n/**\n * Manage widget state that persists across renders via window.openai.setWidgetState\n */\nexport function useWidgetState<T extends Record<string, unknown>>(\n  defaultState: T | (() => T)\n): readonly [T, (state: SetStateAction<T>) => void] {\n  const widgetStateFromWindow = useOpenAiGlobal('widgetState') as T | undefined;\n\n  const [widgetState, _setWidgetState] = useState<T>(() => {\n    if (widgetStateFromWindow != null) {\n      return widgetStateFromWindow;\n    }\n    return typeof defaultState === 'function' ? (defaultState as () => T)() : defaultState;\n  });\n\n  useEffect(() => {\n    if (widgetStateFromWindow != null) {\n      _setWidgetState(widgetStateFromWindow);\n    }\n  }, [widgetStateFromWindow]);\n\n  const setWidgetState = useCallback((state: SetStateAction<T>) => {\n    _setWidgetState((prevState: T) => {\n      const newState = typeof state === 'function' ? (state as (p: T) => T)(prevState) : state;\n      window.openai?.setWidgetState?.(newState);\n      return newState;\n    });\n  }, []);\n\n  return [widgetState, setWidgetState] as const;\n}\n\n// ============================================================================\n// Tool Output Hook\n// ============================================================================\n\n/**\n * Read the tool output (structuredContent) from the MCP server response\n */\nexport function useToolOutput<T = Record<string, unknown>>(): T | undefined {\n  return useOpenAiGlobal('toolOutput') as T | undefined;\n}\n\n/**\n * Read the tool input (arguments) from the tool invocation\n */\nexport function useToolInput<T = Record<string, unknown>>(): T | undefined {\n  return useOpenAiGlobal('toolInput') as T | undefined;\n}\n\n// ============================================================================\n// Theme Hook\n// ============================================================================\n\nexport type ThemeMode = 'light' | 'dark';\n\n/**\n * Get current ChatGPT theme and provide CSS-friendly values\n * Named useChatGPTTheme to avoid conflict with the core useTheme from ThemeProvider\n */\nexport function useChatGPTTheme(): {\n  theme: ThemeMode;\n  isDark: boolean;\n  colors: {\n    background: string;\n    surface: string;\n    surfaceHover: string;\n    border: string;\n    text: string;\n    textMuted: string;\n    accent: string;\n  };\n} {\n  const theme = useOpenAiGlobal('theme') ?? 'dark';\n  const isDark = theme === 'dark';\n\n  return {\n    theme,\n    isDark,\n    colors: isDark ? {\n      background: '#09090b',\n      surface: '#18181b',\n      surfaceHover: '#27272a',\n      border: '#3f3f46',\n      text: '#fafafa',\n      textMuted: '#a1a1aa',\n      accent: '#22d3ee',\n    } : {\n      background: '#ffffff',\n      surface: '#f4f4f5',\n      surfaceHover: '#e4e4e7',\n      border: '#d4d4d8',\n      text: '#18181b',\n      textMuted: '#636370',  // WCAG AA: 5.90:1 on #fff, 5.39:1 on #f4f4f5, 4.66:1 on #e4e4e7 (was #71717a → 4.49:1 FAIL on surface)\n      accent: '#0ea5e9',\n    },\n  };\n}\n\n// ============================================================================\n// Locale Hook\n// ============================================================================\n\n/**\n * Get current locale for internationalization\n */\nexport function useLocale(): string {\n  return useOpenAiGlobal('locale') ?? 'en-US';\n}\n\n// ============================================================================\n// Display Mode Hook\n// ============================================================================\n\n/**\n * Manage widget display mode (inline, PiP, fullscreen)\n */\nexport function useDisplayMode(): {\n  mode: 'inline' | 'pip' | 'fullscreen';\n  maxHeight?: number;\n  requestMode: (mode: 'inline' | 'pip' | 'fullscreen') => Promise<void>;\n  close: () => void;\n} {\n  const mode = useOpenAiGlobal('displayMode') ?? 'inline';\n  const maxHeight = useOpenAiGlobal('maxHeight');\n\n  const requestMode = useCallback(async (newMode: 'inline' | 'pip' | 'fullscreen') => {\n    await window.openai?.requestDisplayMode?.({ mode: newMode });\n  }, []);\n\n  const close = useCallback(() => {\n    window.openai?.requestClose?.();\n  }, []);\n\n  return { mode, maxHeight, requestMode, close };\n}\n\n// ============================================================================\n// Tool Calling Hook\n// ============================================================================\n\n/**\n * Call another MCP tool from within a widget\n */\nexport function useCallTool(): {\n  callTool: <T = unknown>(name: string, args: Record<string, unknown>) => Promise<T>;\n  isLoading: boolean;\n  error: Error | null;\n} {\n  const [isLoading, setIsLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const callTool = useCallback(async <T = unknown>(\n    name: string,\n    args: Record<string, unknown>\n  ): Promise<T> => {\n    if (!window.openai?.callTool) {\n      throw new Error('window.openai.callTool not available');\n    }\n\n    setIsLoading(true);\n    setError(null);\n\n    try {\n      const result = await window.openai.callTool(name, args);\n      return result as T;\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      setError(error);\n      throw error;\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  return { callTool, isLoading, error };\n}\n\n// ============================================================================\n// Follow-up Message Hook\n// ============================================================================\n\n/**\n * Send a follow-up message as if the user asked it\n */\nexport function useSendMessage(): (prompt: string) => Promise<void> {\n  return useCallback(async (prompt: string) => {\n    await window.openai?.sendFollowUpMessage?.({ prompt });\n  }, []);\n}\n\n// ============================================================================\n// Dynamic Height Hook\n// ============================================================================\n\n/**\n * Get the maximum height available for the widget from the host environment.\n * This is the CORRECT pattern per OpenAI Apps SDK examples.\n * \n * The host (ChatGPT/MCPJam) provides maxHeight, and widgets should constrain\n * themselves to this height. Widgets should NOT report their height back.\n * \n * @returns The maximum height in pixels, or undefined if not available\n */\nexport function useMaxHeight(): number | undefined {\n  const [maxHeight, setMaxHeight] = useState<number | undefined>(\n    () => window.openai?.maxHeight\n  );\n  \n  useEffect(() => {\n    const handler = (event: CustomEvent) => {\n      if (event.detail?.globals && 'maxHeight' in event.detail.globals) {\n        setMaxHeight(event.detail.globals.maxHeight);\n      }\n    };\n    \n    window.addEventListener('openai:set_globals', handler as EventListener);\n    return () => window.removeEventListener('openai:set_globals', handler as EventListener);\n  }, []);\n  \n  return maxHeight;\n}\n\n// ============================================================================\n// External Link Hook\n// ============================================================================\n\n/**\n * Open vetted external links in the user's browser\n */\nexport function useOpenExternal(): (href: string) => void {\n  return useCallback((href: string) => {\n    window.openai?.openExternal?.({ href });\n  }, []);\n}\n\n// ============================================================================\n// Utility: Check if running in ChatGPT\n// ============================================================================\n\nexport function isInChatGPT(): boolean {\n  return typeof window !== 'undefined' && window.openai !== undefined;\n}\n\n// ============================================================================\n// Re-exports (types are already exported above)\n// ============================================================================\n\n"],"names":["error"],"mappings":"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"}

package/dist/react/context/SpatialSelectionContext.d.ts

@@ -0,0 +1,40 @@
+import { ReactNode } from 'react';
+
+export interface SpatialSelectionContextValue {
+    /** ID of the currently selected object, or null if nothing is selected. */
+    selectedId: string | null;
+    /** Set the selection (or clear with `null`). */
+    setSelectedId: (id: string | null) => void;
+    /** Toggle selection: select the id if it isn't selected, clear otherwise. */
+    toggleSelection: (id: string) => void;
+    /** Convenience: clear any current selection. */
+    clearSelection: () => void;
+}
+export interface SpatialSelectionProviderProps {
+    children: ReactNode;
+    /** Initial selected id. Default null (nothing selected). */
+    defaultSelectedId?: string | null;
+    /** Controlled mode: when set, the provider mirrors this value instead
+     *  of owning state. Pair with `onSelectionChange`. */
+    selectedId?: string | null;
+    /** Called whenever the selection changes (uncontrolled or controlled). */
+    onSelectionChange?: (id: string | null) => void;
+}
+export declare function SpatialSelectionProvider({ children, defaultSelectedId, selectedId: controlledId, onSelectionChange, }: SpatialSelectionProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the spatial-selection context. Returns `null` when used outside
+ * a `<SpatialSelectionProvider>` — components MUST handle that case so
+ * they stay standalone-usable. Treat the provider as a progressive
+ * enhancement, never a hard dependency.
+ *
+ *   const ctx = useSpatialSelection();
+ *   const selectedId = ctx?.selectedId ?? null;        // safe outside provider
+ *   const onSelect   = ctx?.setSelectedId ?? noop;      // safe outside provider
+ */
+export declare function useSpatialSelection(): SpatialSelectionContextValue | null;
+/**
+ * Strict variant — throws if used outside a provider. Useful in the
+ * provider's own children when the dependency is intentional.
+ */
+export declare function useSpatialSelectionStrict(): SpatialSelectionContextValue;
+export default SpatialSelectionProvider;

package/dist/react/context/SpatialSelectionContext.js

@@ -0,0 +1,10 @@
+import "react/jsx-runtime";
+import { useContext, createContext } from "react";
+const SpatialSelectionContextInternal = createContext(null);
+function useSpatialSelection() {
+  return useContext(SpatialSelectionContextInternal);
+}
+export {
+  useSpatialSelection
+};
+//# sourceMappingURL=SpatialSelectionContext.js.map

package/dist/react/context/SpatialSelectionContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpatialSelectionContext.js","sources":["../../../src/react/context/SpatialSelectionContext.tsx"],"sourcesContent":["/**\n * @zendir/ui - SpatialSelectionContext\n *\n * Optional shared selection state for spatial dashboards. Wrap a tree\n * containing `<ZenSpace3D />`, `<GroundTrackMap />`,\n * `<ObjectInventoryPanel />`, etc. — they cross-talk via the context\n * and stay synchronised without prop-drilling:\n *\n *   <SpatialSelectionProvider>\n *     <ObjectInventoryPanel objects={scene.objects} />  // writes selection\n *     <ZenSpace3D satellites={...} />                   // reads selection\n *     <GroundTrackMap satellites={tracks} />            // reads selection\n *   </SpatialSelectionProvider>\n *\n * The provider is **opt-in**. Components that consume the context use\n * `useSpatialSelection()` which returns `null` outside a provider —\n * that's how every component stays standalone-usable. No coupling.\n */\n\nimport { createContext, useCallback, useContext, useMemo, useState } from 'react';\nimport type { ReactNode } from 'react';\n\n// ─── Types ────────────────────────────────────────────────────────────────────\n\nexport interface SpatialSelectionContextValue {\n  /** ID of the currently selected object, or null if nothing is selected. */\n  selectedId: string | null;\n  /** Set the selection (or clear with `null`). */\n  setSelectedId: (id: string | null) => void;\n  /** Toggle selection: select the id if it isn't selected, clear otherwise. */\n  toggleSelection: (id: string) => void;\n  /** Convenience: clear any current selection. */\n  clearSelection: () => void;\n}\n\nconst SpatialSelectionContextInternal = createContext<SpatialSelectionContextValue | null>(null);\n\n// ─── Provider ─────────────────────────────────────────────────────────────────\n\nexport interface SpatialSelectionProviderProps {\n  children: ReactNode;\n  /** Initial selected id. Default null (nothing selected). */\n  defaultSelectedId?: string | null;\n  /** Controlled mode: when set, the provider mirrors this value instead\n   *  of owning state. Pair with `onSelectionChange`. */\n  selectedId?: string | null;\n  /** Called whenever the selection changes (uncontrolled or controlled). */\n  onSelectionChange?: (id: string | null) => void;\n}\n\nexport function SpatialSelectionProvider({\n  children,\n  defaultSelectedId = null,\n  selectedId: controlledId,\n  onSelectionChange,\n}: SpatialSelectionProviderProps) {\n  const [internalId, setInternalId] = useState<string | null>(defaultSelectedId);\n  const isControlled = controlledId !== undefined;\n  const selectedId = isControlled ? controlledId : internalId;\n\n  const setSelectedId = useCallback(\n    (id: string | null) => {\n      if (!isControlled) setInternalId(id);\n      onSelectionChange?.(id);\n    },\n    [isControlled, onSelectionChange],\n  );\n\n  const toggleSelection = useCallback(\n    (id: string) => {\n      const next = selectedId === id ? null : id;\n      if (!isControlled) setInternalId(next);\n      onSelectionChange?.(next);\n    },\n    [selectedId, isControlled, onSelectionChange],\n  );\n\n  const clearSelection = useCallback(() => {\n    if (!isControlled) setInternalId(null);\n    onSelectionChange?.(null);\n  }, [isControlled, onSelectionChange]);\n\n  const value = useMemo<SpatialSelectionContextValue>(\n    () => ({ selectedId, setSelectedId, toggleSelection, clearSelection }),\n    [selectedId, setSelectedId, toggleSelection, clearSelection],\n  );\n\n  return (\n    <SpatialSelectionContextInternal.Provider value={value}>\n      {children}\n    </SpatialSelectionContextInternal.Provider>\n  );\n}\n\n// ─── Hooks ────────────────────────────────────────────────────────────────────\n\n/**\n * Read the spatial-selection context. Returns `null` when used outside\n * a `<SpatialSelectionProvider>` — components MUST handle that case so\n * they stay standalone-usable. Treat the provider as a progressive\n * enhancement, never a hard dependency.\n *\n *   const ctx = useSpatialSelection();\n *   const selectedId = ctx?.selectedId ?? null;        // safe outside provider\n *   const onSelect   = ctx?.setSelectedId ?? noop;      // safe outside provider\n */\nexport function useSpatialSelection(): SpatialSelectionContextValue | null {\n  return useContext(SpatialSelectionContextInternal);\n}\n\n/**\n * Strict variant — throws if used outside a provider. Useful in the\n * provider's own children when the dependency is intentional.\n */\nexport function useSpatialSelectionStrict(): SpatialSelectionContextValue {\n  const ctx = useContext(SpatialSelectionContextInternal);\n  if (!ctx) {\n    throw new Error(\n      'useSpatialSelectionStrict() called outside <SpatialSelectionProvider>. ' +\n        'Wrap the tree, or use useSpatialSelection() (returns null) for opt-in usage.',\n    );\n  }\n  return ctx;\n}\n\nexport default SpatialSelectionProvider;\n"],"names":[],"mappings":";;AAmCA,MAAM,kCAAkC,cAAmD,IAAI;AAuExF,SAAS,sBAA2D;AACzE,SAAO,WAAW,+BAA+B;AACnD;"}

package/dist/react/context/index.d.ts

@@ -5,3 +5,5 @@ export { DisplaySettingsProvider, useDisplaySettings, useDisplaySettingsOptional
 export type { DisplaySettings, DisplaySettingsContextValue, DisplaySettingsProviderProps, ColorTarget, PresetColorKey, GlassTintKey, } from './DisplaySettingsContext';
 export { CategoryProvider, useCategoryPalette, useCategoryPaletteRequired, } from './CategoryContext';
 export type { CategoryContextValue, CategoryProviderProps, } from './CategoryContext';
+export { SpatialSelectionProvider, useSpatialSelection, useSpatialSelectionStrict, } from './SpatialSelectionContext';
+export type { SpatialSelectionContextValue, SpatialSelectionProviderProps, } from './SpatialSelectionContext';

package/dist/react/core/{DataTable.d.ts → data/DataTable.d.ts}

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { TooltipPlacement } from './Tooltip';
+import { TooltipPlacement } from '../overlays/Tooltip';
 
 export interface DataTableColumn<T = Record<string, unknown>> {
     /** Key in data object */

package/dist/react/core/{DataTable.js → data/DataTable.js}

@@ -1,9 +1,9 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import React, { memo, useMemo, useState, useCallback } from "react";
-import { useBreakpoint } from "./layout/useBreakpoint.js";
-import { Tooltip } from "./Tooltip.js";
-import { addAlpha } from "../utils/index.js";
-import { useTheme } from "../theme/ThemeProvider.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import { useBreakpoint } from "../layout/useBreakpoint.js";
+import { Tooltip } from "../overlays/Tooltip.js";
+import { addAlpha } from "../../utils/index.js";
 const STATUS_DOT_COLORS = {
   normal: "#56F000",
   caution: "#FCE83A",