@aura-react-comp/x 0.0.0-stage → 0.1.0

package/esm/use-x-chat/index.js

@@ -0,0 +1,178 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isAbortError } from "../use-x-stream";
+
+/** 一条对话消息 */
+
+/** onRequest 收到的上下文 */
+
+/** 默认消息的来源：定长数组，或按会话动态求值（可异步，用于拉取历史） */
+
+const cloneMessages = messages => messages.map(message => ({
+  ...message
+}));
+
+/**
+ * useXChat — 对话消息编排 Hook（与传输层 useXStream 正交）。
+ *
+ * 职责：维护消息列表状态机（user / assistant 成对追加、loading 态、
+ * 增量更新、错误态、中止与清空），并按 `conversationKey` 管理多会话切换。
+ * **不做传输**——怎么请求由 `onRequest` 决定，典型组合是内部调用
+ * `useXStream().fetchData` 并在 onMessage 里 `update` 内容。
+ */
+export function useXChat({
+  conversationKey,
+  defaultMessages,
+  initialMessages = [],
+  onRequest,
+  onError
+}) {
+  const source = defaultMessages ?? initialMessages;
+
+  // 用 ref 持有最新的来源：它只在 conversationKey 变化时被读取，
+  // 因此调用方传数组字面量也不会每次渲染都触发重置。
+  const sourceRef = useRef(source);
+  sourceRef.current = source;
+  const [messages, setMessagesState] = useState(() => Array.isArray(source) ? cloneMessages(source) : []);
+  const [loading, setLoading] = useState(false);
+  const [isDefaultMessagesRequesting, setRequesting] = useState(false);
+  const counterRef = useRef(0);
+  const abortRef = useRef(null);
+  /** 最近一次解析出的默认消息，供 clear() 复位使用 */
+  const baselineRef = useRef(Array.isArray(source) ? cloneMessages(source) : []);
+  const mountedRef = useRef(true);
+  const keyRef = useRef(conversationKey);
+  keyRef.current = conversationKey;
+  const nextId = () => `x-msg-${++counterRef.current}`;
+
+  /**
+   * 按 id 定位 assistant 消息。
+   *
+   * 刻意**不**用「当前 assistant id」这样的 ref：切换会话会中止旧请求，
+   * 而旧请求的收尾是异步的；若收尾时去读共享 ref，就会把新会话里
+   * 刚创建的 assistant 占位误标为完成。把 id 捕获在闭包里才没有这个竞态。
+   */
+  const patchById = useCallback((id, patch) => {
+    setMessagesState(prev => prev.map(message => message.id === id ? {
+      ...message,
+      ...patch
+    } : message));
+  }, []);
+
+  /** 仅把「仍是 loading」的那条置为 success，不覆盖 error 态 */
+  const settleById = useCallback(id => {
+    setMessagesState(prev => prev.map(message => message.id === id && message.status === 'loading' ? {
+      ...message,
+      status: 'success'
+    } : message));
+  }, []);
+
+  /** 求值默认消息：数组直接克隆，函数则调用（可能返回 Promise） */
+  const resolveDefault = useCallback(async () => {
+    const current = sourceRef.current;
+    const resolved = typeof current === 'function' ? await current({
+      conversationKey: keyRef.current
+    }) : current;
+    return cloneMessages(resolved ?? []);
+  }, []);
+
+  // 挂载 + conversationKey 变化：重新初始化消息
+  useEffect(() => {
+    let cancelled = false;
+    const first = mountedRef.current;
+    mountedRef.current = false;
+
+    // 挂载时若来源是数组，useState 初值已经处理过，无需再走一遍
+    if (first && !(typeof sourceRef.current === 'function')) return undefined;
+
+    // 切换会话：先中止旧请求，避免它的增量写进新会话
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setLoading(false);
+    setRequesting(true);
+    void (async () => {
+      try {
+        const next = await resolveDefault();
+        if (cancelled) return;
+        baselineRef.current = next;
+        setMessagesState(next);
+      } finally {
+        if (!cancelled) setRequesting(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [conversationKey, resolveDefault]);
+  const send = useCallback(content => {
+    if (loading) return; // 串行语义：进行中的请求未结束时忽略新发送
+    if (!content.trim()) return; // 空白内容忽略
+
+    const userMessage = {
+      id: nextId(),
+      role: 'user',
+      content
+    };
+    const assistantMessage = {
+      id: nextId(),
+      role: 'assistant',
+      content: '',
+      status: 'loading'
+    };
+    const assistantId = assistantMessage.id;
+    const history = cloneMessages([...messages, userMessage, assistantMessage]);
+    setMessagesState(history);
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setLoading(true);
+    void (async () => {
+      try {
+        await onRequest({
+          message: content,
+          messages: history,
+          signal: controller.signal,
+          update: patch => patchById(assistantId, patch)
+        });
+        settleById(assistantId);
+      } catch (error) {
+        // stop() / 切换会话触发的 abort 属正常结束：保留已生成的部分内容
+        if (isAbortError(error)) {
+          settleById(assistantId);
+          return;
+        }
+        patchById(assistantId, {
+          status: 'error'
+        });
+        onError?.(error instanceof Error ? error : new Error(String(error)));
+      } finally {
+        // 只有当这次请求仍是「当前请求」时才收尾：切换会话后旧的收尾
+        // 不能把新会话刚点亮的 loading 态按下去
+        if (abortRef.current === controller) {
+          abortRef.current = null;
+          setLoading(false);
+        }
+      }
+    })();
+  }, [loading, messages, onRequest, onError, patchById, settleById]);
+  const stop = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+  const clear = useCallback(() => {
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setLoading(false);
+    setMessagesState(cloneMessages(baselineRef.current));
+  }, []);
+  const setMessages = useCallback(next => {
+    // 直接替换，不触发请求；进行中的请求若仍在跑，其 update 会因 id 失配而落空
+    setMessagesState(cloneMessages(next));
+  }, []);
+  return {
+    messages,
+    loading,
+    isDefaultMessagesRequesting,
+    send,
+    stop,
+    clear,
+    setMessages
+  };
+}

package/esm/use-x-stream/index.d.ts

@@ -0,0 +1,43 @@
+import { type XStreamChunk } from './parse-sse';
+export type { XStreamChunk } from './parse-sse';
+export interface FetchDataStreamOptions {
+    /** 流式接口地址 */
+    url: string;
+    /** 缺省：body 存在时为 POST，否则 GET */
+    method?: string;
+    headers?: Record<string, string>;
+    /**
+     * 请求体。传普通对象时自动 `JSON.stringify` 并设置 `Content-Type: application/json`；
+     * FormData / Blob 等特殊类型请自行序列化后以字符串传入。
+     */
+    body?: unknown;
+    /** 每解析出一条消息回调一次 */
+    onMessage(chunk: XStreamChunk): void;
+    /** 流正常结束（含 abort 静默结束）后回调 */
+    onDone?(): void;
+    /** 请求或读流出错（abort 不算）后回调 */
+    onError?(error: Error): void;
+}
+export interface UseXStreamResult {
+    /** 是否有进行中的流式请求 */
+    streaming: boolean;
+    /**
+     * 发起一次流式请求并逐条消费。同一时刻只保留一条流：
+     * 再次 fetchData 会先 abort 上一次（静默结束，不触发 onError）。
+     */
+    fetchData(options: FetchDataStreamOptions): Promise<void>;
+    /** 中止当前流（静默结束：不触发 onError） */
+    abort(): void;
+}
+/** 判定是否为 abort 导致的错误（fetch / 读流被 signal 中断时抛出） */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * useXStream — 流式传输层 Hook。
+ *
+ * 负责：fetch + 读流 + SSE / 纯文本两种模式的解析 + abort 生命周期，
+ * **不做任何消息状态管理**（那是 useXChat 的职责），两者保持正交。
+ *
+ * - 响应 `Content-Type` 含 `text/event-stream` → 按 SSE 解析；
+ * - 其余类型按「纯文本增量流」处理，每个字节块原样作为一条消息产出。
+ */
+export declare function useXStream(): UseXStreamResult;

package/esm/use-x-stream/index.js

@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { parseSSEStream } from "./parse-sse";
+/** 判定是否为 abort 导致的错误（fetch / 读流被 signal 中断时抛出） */
+export function isAbortError(error) {
+  return error instanceof DOMException ? error.name === 'AbortError' : error instanceof Error && error.name === 'AbortError';
+}
+
+/**
+ * useXStream — 流式传输层 Hook。
+ *
+ * 负责：fetch + 读流 + SSE / 纯文本两种模式的解析 + abort 生命周期，
+ * **不做任何消息状态管理**（那是 useXChat 的职责），两者保持正交。
+ *
+ * - 响应 `Content-Type` 含 `text/event-stream` → 按 SSE 解析；
+ * - 其余类型按「纯文本增量流」处理，每个字节块原样作为一条消息产出。
+ */
+export function useXStream() {
+  const [streaming, setStreaming] = useState(false);
+  const controllerRef = useRef(null);
+  const mountedRef = useRef(true);
+
+  // 卸载时中止在途流，避免对已卸载组件回调 setState
+  useEffect(() => () => {
+    mountedRef.current = false;
+    controllerRef.current?.abort();
+  }, []);
+  const abort = useCallback(() => {
+    controllerRef.current?.abort();
+  }, []);
+  const fetchData = useCallback(async options => {
+    // 串行语义：新请求先中止上一次（静默结束，不触发其 onError）
+    controllerRef.current?.abort();
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    setStreaming(true);
+    const finishStreaming = () => {
+      if (mountedRef.current) setStreaming(false);
+      if (controllerRef.current === controller) controllerRef.current = null;
+    };
+    try {
+      const headers = {
+        Accept: 'text/event-stream',
+        ...options.headers
+      };
+      let body;
+      const raw = options.body;
+      if (raw !== undefined && raw !== null) {
+        if (typeof raw === 'object') {
+          var _ContentType;
+          body = JSON.stringify(raw);
+          headers[_ContentType = 'Content-Type'] ?? (headers[_ContentType] = 'application/json');
+        } else {
+          body = raw;
+        }
+      }
+      const response = await fetch(options.url, {
+        method: options.method ?? (body !== undefined ? 'POST' : 'GET'),
+        headers,
+        body,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`[XStream] 请求失败：${response.status} ${response.statusText || ''}`.trim());
+      }
+      const contentType = response.headers.get('Content-Type') ?? '';
+      if (response.body && contentType.includes('text/event-stream')) {
+        // SSE 模式
+        for await (const chunk of parseSSEStream(response.body)) {
+          options.onMessage(chunk);
+        }
+      } else if (response.body) {
+        // 纯文本增量流模式：每个字节块原样产出
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        while (true) {
+          const {
+            done,
+            value
+          } = await reader.read();
+          if (done) break;
+          const text = decoder.decode(value, {
+            stream: true
+          });
+          if (text) options.onMessage({
+            data: text,
+            event: 'message'
+          });
+        }
+      } else {
+        // 兜底：无读流的响应，整体作为一条消息
+        const text = await response.text();
+        if (text) options.onMessage({
+          data: text,
+          event: 'message'
+        });
+      }
+      options.onDone?.();
+    } catch (error) {
+      // abort 是主动停止，属于「正常结束」，静默处理
+      if (!isAbortError(error)) {
+        options.onError?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    } finally {
+      finishStreaming();
+    }
+  }, []);
+  return {
+    streaming,
+    fetchData,
+    abort
+  };
+}

package/esm/use-x-stream/parse-sse.d.ts

@@ -0,0 +1,19 @@
+/** SSE 解析出的单条消息 */
+export interface XStreamChunk {
+    /** data 字段内容；多行 data 以 \n 拼接 */
+    data: string;
+    /** event 字段，缺省为 "message" */
+    event: string;
+    /** id 字段（可选） */
+    id?: string;
+}
+/**
+ * 把字节流解析为 SSE 消息的异步生成器。
+ *
+ * 兼容性处理：BOM、CRLF / LF 混用、多行 data（以 \n 拼接）、注释行与心跳帧
+ * （无 data，不产出消息）、流结束时未以空行收尾的最后一条帧（宽容产出）。
+ *
+ * `data: [DONE]` 等「结束哨兵」不做特殊处理，原样产出，由消费方过滤——
+ * 解析器保持协议无关。
+ */
+export declare function parseSSEStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<XStreamChunk, void, unknown>;

package/esm/use-x-stream/parse-sse.js

@@ -0,0 +1,91 @@
+// SSE（text/event-stream）字节流 → 消息对象的解析器。
+//
+// 纯函数、UI 无关：输入 ReadableStream，输出异步生成器，便于单测（可用
+// ReadableStream 造任意帧序列）与复用（useXStream 之外的场景也能用）。
+
+/** SSE 解析出的单条消息 */
+
+/** 找到下一个帧分隔符（空行）的位置；分隔符兼容 \n\n 与 \r\n\r\n */
+function findFrameEnd(buffer) {
+  const lf = buffer.indexOf('\n\n');
+  const crlf = buffer.indexOf('\r\n\r\n');
+  if (lf === -1) return crlf;
+  if (crlf === -1) return lf;
+  return Math.min(lf, crlf);
+}
+
+/** 分隔符长度取决于命中的是 LF 还是 CRLF 形式 */
+function frameEndLength(buffer, index) {
+  return buffer.startsWith('\r\n\r\n', index) ? 4 : 2;
+}
+
+/** 解析单个 SSE 帧；无 data 内容的帧（注释 / 心跳）返回 null */
+function parseFrame(frame) {
+  let event = 'message';
+  let id;
+  const dataLines = [];
+  for (const rawLine of frame.split(/\r?\n/)) {
+    // 空行与注释行（以冒号开头，如 ": ping"）按规范忽略
+    if (!rawLine || rawLine.startsWith(':')) continue;
+    const colon = rawLine.indexOf(':');
+    const field = colon === -1 ? rawLine : rawLine.slice(0, colon);
+    let value = colon === -1 ? '' : rawLine.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (field === 'data') dataLines.push(value);else if (field === 'event') event = value;else if (field === 'id') id = value;
+    // retry 等其余字段第一版不消费
+  }
+  const data = dataLines.join('\n');
+  if (!data) return null;
+  return id !== undefined ? {
+    data,
+    event,
+    id
+  } : {
+    data,
+    event
+  };
+}
+
+/**
+ * 把字节流解析为 SSE 消息的异步生成器。
+ *
+ * 兼容性处理：BOM、CRLF / LF 混用、多行 data（以 \n 拼接）、注释行与心跳帧
+ * （无 data，不产出消息）、流结束时未以空行收尾的最后一条帧（宽容产出）。
+ *
+ * `data: [DONE]` 等「结束哨兵」不做特殊处理，原样产出，由消费方过滤——
+ * 解析器保持协议无关。
+ */
+export async function* parseSSEStream(stream) {
+  const decoder = new TextDecoder('utf-8');
+  const reader = stream.getReader();
+  let buffer = '';
+  try {
+    while (true) {
+      const {
+        done,
+        value
+      } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, {
+        stream: true
+      });
+      buffer = buffer.replace(/^\uFEFF/, '');
+      let index = findFrameEnd(buffer);
+      while (index !== -1) {
+        const frame = buffer.slice(0, index);
+        buffer = buffer.slice(index + frameEndLength(buffer, index));
+        const chunk = parseFrame(frame);
+        if (chunk) yield chunk;
+        index = findFrameEnd(buffer);
+      }
+    }
+
+    // 流结束但缓冲区还有内容：宽容地把最后一条未以空行收尾的帧产出
+    if (buffer.trim()) {
+      const chunk = parseFrame(buffer);
+      if (chunk) yield chunk;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/esm/utils/color.d.ts

@@ -0,0 +1,9 @@
+type Rgb = [number, number, number];
+export declare function hexToRgb(hex: string): Rgb | null;
+/** hex → rgba() 字符串 */
+export declare function toRgba(hex: string, alpha: number): string | null;
+/** 向白色混合（ratio = 0 原色，1 纯白）——用于渐变的亮端 */
+export declare function lighten(hex: string, ratio: number): string | null;
+/** 由主色派生的 CSS 变量集（对应 tokens.css 中 --aura-x-* 的品牌相关子集） */
+export declare function deriveAccentVars(primary: string): Record<string, string> | null;
+export {};

package/esm/utils/color.js

@@ -0,0 +1,45 @@
+// 主题派生工具：从主色推导 --aura-x-* 动态变量（渐变 / 透明度 / 光晕）。
+// 仅处理 hex 输入（#rgb / #rrggbb）；无法解析时返回 null，由调用方兜底。
+
+export function hexToRgb(hex) {
+  const normalized = hex.trim().replace(/^#/, '');
+  const full = normalized.length === 3 ? normalized.split('').map(c => c + c).join('') : normalized;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
+  const value = parseInt(full, 16);
+  return [value >> 16 & 255, value >> 8 & 255, value & 255];
+}
+
+/** hex → rgba() 字符串 */
+export function toRgba(hex, alpha) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  return `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${alpha})`;
+}
+
+/** 向白色混合（ratio = 0 原色，1 纯白）——用于渐变的亮端 */
+export function lighten(hex, ratio) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  const mixed = rgb.map(channel => Math.round(channel + (255 - channel) * ratio));
+  return `#${mixed.map(c => c.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/** 由主色派生的 CSS 变量集（对应 tokens.css 中 --aura-x-* 的品牌相关子集） */
+export function deriveAccentVars(primary) {
+  const rgb = hexToRgb(primary);
+  if (!rgb) return null;
+  const lightEnd = lighten(primary, 0.22) ?? primary;
+  const glowColor = toRgba(primary, 0.28) ?? `rgba(124, 58, 237, 0.28)`;
+  const ringColor = toRgba(primary, 0.16) ?? `rgba(124, 58, 237, 0.16)`;
+  const softColor = toRgba(primary, 0.08) ?? `rgba(124, 58, 237, 0.08)`;
+  const borderColor = toRgba(primary, 0.22) ?? `rgba(124, 58, 237, 0.22)`;
+  return {
+    '--aura-x-accent': primary,
+    '--aura-x-accent-gradient': `linear-gradient(135deg, ${primary} 0%, ${lightEnd} 100%)`,
+    '--aura-x-accent-soft': softColor,
+    '--aura-x-bubble-user-bg': `linear-gradient(135deg, ${primary} 0%, ${lightEnd} 100%)`,
+    '--aura-x-bubble-border': borderColor,
+    '--aura-x-glow': `0 0 0 1px ${toRgba(primary, 0.16)}, 0 12px 32px -8px ${glowColor}`,
+    '--aura-x-focus-ring': `0 0 0 3px ${ringColor}`
+  };
+}

package/esm/welcome/index.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+export interface WelcomeProps {
+    /** 顶部图标 / 头像（如 Logo、渐变球） */
+    icon?: React.ReactNode;
+    /** 欢迎标题（如「早上好，Landy」） */
+    title?: React.ReactNode;
+    /** 副标题 / 描述 */
+    description?: React.ReactNode;
+    /** 附加内容插槽（常放 Prompts 提示词集） */
+    extra?: React.ReactNode;
+    /** board：带边框面板；simple：纯内容 */
+    variant?: 'board' | 'simple';
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Welcome — 对话开始前的欢迎区。
+ *
+ * 典型用法：icon + title + description 居中展示，
+ * `extra` 里放 [`Prompts`](/x-components/prompts) 引导用户开口。
+ */
+export declare const Welcome: React.FC<WelcomeProps>;

package/esm/welcome/index.js

@@ -0,0 +1,36 @@
+import React from 'react';
+import { classNames, prefixCls } from '@aura-react-comp/shared';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Welcome — 对话开始前的欢迎区。
+ *
+ * 典型用法：icon + title + description 居中展示，
+ * `extra` 里放 [`Prompts`](/x-components/prompts) 引导用户开口。
+ */
+export const Welcome = ({
+  icon,
+  title,
+  description,
+  extra,
+  variant = 'board',
+  className,
+  style
+}) => /*#__PURE__*/_jsxs("div", {
+  className: classNames(prefixCls('x-welcome'), prefixCls(`x-welcome--${variant}`), className),
+  style: style,
+  children: [icon ? /*#__PURE__*/_jsx("div", {
+    className: prefixCls('x-welcome-icon'),
+    children: icon
+  }) : null, title ? /*#__PURE__*/_jsx("div", {
+    className: prefixCls('x-welcome-title'),
+    children: title
+  }) : null, description ? /*#__PURE__*/_jsx("div", {
+    className: prefixCls('x-welcome-description'),
+    children: description
+  }) : null, extra ? /*#__PURE__*/_jsx("div", {
+    className: prefixCls('x-welcome-extra'),
+    children: extra
+  }) : null]
+});
+Welcome.displayName = 'Welcome';

package/esm/welcome/index.less

@@ -0,0 +1,57 @@
+/* Welcome — 欢迎区（顶部光晕 + 渐变图标底座） */
+
+.aura-x-welcome {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--aura-spacing-3);
+  padding: var(--aura-spacing-6) var(--aura-spacing-4);
+  text-align: center;
+  overflow: hidden;
+}
+
+.aura-x-welcome--board {
+  border: 1px solid var(--aura-x-bubble-border);
+  border-radius: var(--aura-radius-lg);
+  background:
+    radial-gradient(
+      560px 180px at 50% -60px,
+      var(--aura-x-accent-soft),
+      transparent 70%
+    ),
+    var(--aura-x-bubble-ai-bg);
+  backdrop-filter: var(--aura-x-glass-blur);
+  -webkit-backdrop-filter: var(--aura-x-glass-blur);
+}
+
+/* 图标底座：渐变圆角方块 + 光晕 */
+.aura-x-welcome-icon {
+  display: grid;
+  place-items: center;
+  width: 56px;
+  height: 56px;
+  border-radius: var(--aura-radius-lg);
+  background: var(--aura-x-accent-gradient);
+  color: #fff;
+  font-size: 28px;
+  line-height: 1;
+  box-shadow: var(--aura-x-glow);
+}
+
+.aura-x-welcome-title {
+  font-size: var(--aura-font-size-2xl);
+  font-weight: 600;
+  color: var(--aura-text);
+  letter-spacing: 0.2px;
+}
+
+.aura-x-welcome-description {
+  font-size: var(--aura-font-size-sm);
+  color: var(--aura-text-secondary);
+  max-width: 480px;
+}
+
+.aura-x-welcome-extra {
+  margin-top: var(--aura-spacing-2);
+  width: 100%;
+}

package/esm/x-provider/index.d.ts

@@ -0,0 +1,48 @@
+import React from 'react';
+import type { Locale } from 'antd/es/locale';
+import type { ThemeConfig } from 'antd';
+export interface XProviderProps {
+    children: React.ReactNode;
+    /** 暗色模式：切换 antd 暗色算法，并在子树作用域启用暗色令牌（data-theme="dark"） */
+    dark?: boolean;
+    /** 是否启用紧凑模式 */
+    compact?: boolean;
+    /**
+     * 主题主色。组件视觉（渐变 / 光晕 / 软底）由它**实时派生**：
+     * 换主色，所有 --aura-x-* 品牌变量即时跟随。
+     * @default auraTokens.colors.primary[700] (#7c3aed)
+     */
+    colorPrimary?: string;
+    /**
+     * 语言包
+     * @default zhCN
+     */
+    locale?: Locale;
+}
+export interface XThemeConfigOptions {
+    dark?: boolean;
+    compact?: boolean;
+    colorPrimary?: string;
+}
+/**
+ * 组装 XProvider 的 antd 主题配置。
+ *
+ * 令牌覆盖集来自 @aura-react-comp/shared 的单一数据源（与 BusinessProvider 共用）；
+ * 这里只负责 algorithm 的组装：暗色 / 默认 + 可选紧凑。
+ * 导出以便单测直接断言配置内容。
+ */
+export declare function buildXThemeConfig({ dark, compact, colorPrimary }: XThemeConfigOptions): ThemeConfig;
+/**
+ * XProvider — AI 组件主题桥接
+ *
+ * 将 Aura 设计令牌映射到 antd 的主题系统，为 AI 对话组件（Bubble / Sender 等）
+ * 提供与 @aura-react-comp/ui、@aura-react-comp/business 一致的紫罗兰视觉语言。
+ *
+ * antd v6 默认使用 CSS Variables，因此可与 Aura 的 CSS 变量主题体系共存。
+ *
+ * 主题派生：`colorPrimary` 会实时派生整套 `--aura-x-*` 品牌变量（渐变 / 光晕 /
+ * 软底 / 边框），注入到子树作用域——Bubble / Sender / MarkdownContent 等
+ * 组件消费这些变量，因此**换主色即时全量生效**；`dark` 同时在子树启用
+ * `data-theme="dark"` 暗色令牌。
+ */
+export declare const XProvider: React.FC<XProviderProps>;