组件总览

AI 聊天输入框：基于 tiptap 富文本编辑器（内核 + svelte-tiptap 动态 import 懒加载，绝不进主 bundle）。阶段 1 富文本输入 + 发送（sendHotKey、canSend、generating 停止键）+ Upload 附件。阶段 2 references 引用条（可点击/删除/renderReference 覆盖）+ suggestions 建议浮层（聚焦弹出，↑↓/Enter/Esc/点击外部，renderSuggestionItem 覆盖）+ renderTopSlot。阶段 3 skills 技能面板（空编辑区按 skillHotKey 弹出，↑↓/Enter/Esc，选中插入 skill-slot 自定义节点并 onSkillChange）+ skill-slot NodeView（inline atom chip，含删除，用 svelte-tiptap SvelteNodeViewRenderer 渲染 SkillSlotNode.svelte）+ renderTemplate 模版面板（当前技能 hasTemplate 时展示模版按钮，点击弹出，setContent 填入）。阶段 4 renderConfigureArea 配置区（footer 左侧，放 AIChatInputConfigureSelect/Button/RadioButton 经 configure context 用 field 绑定）+ configureDefaultValue + onConfigureChange，配置值发送时并入 MessageContent.setup。onMessageSend 载荷对齐 Semi MessageContent（inputContents/attachments/references/setup）。headless（canSend/sendHotKey/MessageContent/doc→contents/suggestion 键盘/reference 归一/skill 归一/getSkillSlotHTML/skillHotKey 判定/configure setField-removeField）在 @chenzy-design/core，可单测。ref 方法 setContent/focusEditor/getText/getHTML/getEditor/clearContent/changeTemplateVisible/getConfigureValue。阶段 5 Adapter 桥（chatInputToMessage → AIDialogueMessage 喂 AIChatDialogue；chatInputToChatCompletion → OpenAI ChatCompletion user message）为 core 纯函数，从 svelte 包透传。

AI 对话展示：消息格式以 OpenAI Response Object 为原型，content 支持 ContentItem[]（output_text/input_text 走 MarkdownRender、image、file、reasoning 折叠块、function_call/tool_call 工具块、refusal、audio）。逐条 DialogueBox 渲染，ContentItemRenderer 按 type 分派、renderDialogueContentItem 可覆盖。消息流 role=log/aria-live=polite；滚动出现回到底部；选择模式 checkbox。ref 方法 selectAll/deselectAll/scrollToBottom/scrollToTop。core 提供类型全谱 + 非流式 Adapter（responseToMessage / chatCompletionToMessage）+ 流式 Adapter（streamingResponseToMessage 全功能增量状态机：sequence_number 顺序处理/无序缓冲/MAX_GAP 容错/20+ chunk 类型 delta 累积；streamingChatCompletionToMessage：choice.index 分组/processedCount 增量/tool_calls 累积），全功能对齐 Semi。

AI 侧边信息栏套件（重量级组合，分阶段交付）：P0 SideBarContainer 为可伸缩浮层壳——贴视口右侧（RTL 贴左），role=dialog + aria-labelledby(title)，打开移焦 + focus-trap 焦点捕获/归还 + Esc 关闭，堆叠 z-index 与 Modal/SideSheet 统一层栈（后开者在上），resizable 时左边缘（RTL 右边缘）把手拖拽调宽——复用 core createResizeDrag（axis:x 单轴 + clamp minWidth/maxWidth）与 Resizable 同套把手 a11y（role=separator + aria-orientation=vertical + aria-valuenow + 键盘 ←→/Home/End），motion 展开/收起为 CSS transition（reduced-motion / motion=false 退化即时显隐）。P1 SideBar 主壳按 mode 路由：main 渲染顶部 Options 图标 tab 组（每项是本库 Button，图标 + name 可见文字，之上叠加 role=tablist + roving tabindex + 键盘）+ renderMainContent(activeKey)；detail（code/file/自定义）渲染 renderDetailHeader + 返回按钮（onBackWard 可异步，await 期间禁用防重触发）+ renderDetailContent(mode)。受控 visible / activeKey（不回写，仅回调通知）。P2 SideBarAnnotation 参考来源/引用溯源：外层复用 SideBarContainer 浮层壳（透传全部 Container props，title 默认走 i18n annotationTitle），内部渲染 SideBarAnnotationContent（对齐 Semi Annotation.AnnotationContent 静态属性，可脱离 Container 独立使用，例如嵌入 renderMainContent）——用 Collapse 渲染 info 分组（每组一折叠面板 + aria-expanded，clickHeaderToExpand=false），展开区渲染 video（封面/时长/具名 IconPlay 播放按钮贴右上角/时长徽标）/text（站点 logo/名称/引用序号）卡片；可点击卡片（url 或 onClick）用原生 button（键盘 Enter/Space + focus 环 + 时长/序号本地化可访问文本），renderItem 可整条覆盖。P4 SideBarCodeContent 代码/JSON 预览：Collapse 折叠列表（clickHeaderToExpand=false），每项按 isJson 分流 JsonViewer / CodeHighlight（透传 jsonViewerProps/codeHighlightProps），头部具名图标 + Button(theme=borderless type=tertiary) 展开（全屏）按钮，onExpand 回调。P3 SideBarMCPConfigure MCP 工具配置面板：外层复用 SideBarContainer（title 默认走 i18n mcpTitle），内部顶部已启用计数 + RadioGroup(type=button) 在内置/自定义两模式间切换（对齐 Semi，同一时刻只渲染一份列表）+ 搜索框（Input，前缀放大镜 + aria-label，headless filterMcpOptions 支持自定义 filter）；每项前置图标（string→img / Snippet）+ label + desc + 动作按钮（内置 Button+IconSetting 显示配置 / 自定义 Button+IconEdit 显示编辑，aria-label 含工具名）+ 启用开关（Button(theme=active?light:solid type=primary) + IconMinus/IconPlus，对齐 Semi renderStatusButton，非开关组件；disabled 预设项锁定 + Tooltip 提示），启用变化经 core toggleMcpOptionActive 产出「下一份数组 + custom 标记」上抛 onStatusChange 不回写；自定义组空态用 Empty + IllustrationNoContent(Dark) 插画 + 添加按钮，无搜索结果显示提示。P5 SideBarFileContent 富文本查看/编辑：Collapse 折叠列表（clickHeaderToExpand=false），每项 SideBarFileItem 一个 tiptap v3 编辑器（editable 控查看/编辑，编辑态渲染格式工具栏），默认扩展集对齐 Semi（StarterKit link openOnClick:false + TextStyleKit + Image + TextAlign + 自研 SelectionMark + 自研 ImageUploadNode，末尾拼接 extensions），onContentChange 回调 editor.getHTML()；ImageUploadNode 用 svelte-tiptap NodeViewRenderer 内嵌本库 Upload（draggable + getUploadImageSrc，默认 listType 不显式传，随 Upload 默认值）；tiptap 内核 + 3 官方扩展（text-style/image/text-align）+ svelte-tiptap 全程动态 import 不进主 bundle。

页面级布局骨架：Layout 根容器 + Header / Sider / Content / Footer 子组件。纯布局容器，不附带背景/尺寸样式，按需自定义。

24 栅格布局：Row 容器 + Col 列，严格对齐 Semi。默认 Row=cd-row（display:block + clearfix），Col 用 float:left + width% 布局；Row type="flex" 时切 flex 布局并激活 justify/align（cd-row-flex-{justify}/-{align}）。gutter 经 context 下发到 Col：Row 施加四向负 margin、Col 施加四向 padding 抵消，支持 [x,y] 与响应式对象（screens 状态机 + responsiveArray 从大到小降级）。Col 响应式为纯 CSS 类驱动（cd-col-{bp}-{span} 等，靠 @media 断点层叠）。

可伸缩组件族：Resizable 单体容器（4 边 + 4 角共 8 个可选把手，拖拽改自身宽/高，支持 min/max、锁比例、网格吸附、缩放/像素比修正、边界限制）与 ResizeGroup/ResizeItem/ResizeHandler 分栏组（水平/垂直多面板，相邻两项联动一增一减、总和守恒，各项 min/max clamp 后重分配）。严格对齐 Semi Design：把手是裸 div（无 role/aria/tabindex/键盘），ResizeHandler 默认渲染 IconHandle。core 沉淀通用拖拽原语 createResizeDrag（单次拖拽生命周期，命令式绑/解全局监听）+ computeGroupResize（分栏联动几何），供 Table 列宽拖拽、SideBar Container 复用。

触发即时操作的按钮，最基础的交互原子（严格对齐 Semi Button）。

悬浮固定在视口的可操作按钮，用于承载全局快捷入口（AI 编辑、搜索、帮助等）。严格对齐 Semi：纯 div + onClick（非 button/a），href 靠 JS 跳转（target=_blank 用 window.open，否则 location.href），disabled 时不触发。可选包裹 Badge。形状 round(默认)/square、尺寸 small/default/large、colorful AI 渐变。默认 position:fixed 于右下角（bottom/right 24px），经 style 覆盖定位。FloatButtonGroup 将多项平铺成胶囊工具条，点击委托直接读 e.target.dataset.value 回传 value。

排版家族：Title / Text / Paragraph / Numeral，统一文本样式与语义色（严格对齐 Semi）。

分隔线，用于在视觉上分割内容区块，纯展示。严格对齐 Semi Design。

统一尺寸、颜色、对齐的矢量图标容器，纯展示原语（对齐 Semi Icon 基类）。

间距布局容器，在一组相邻子元素之间施加统一、可控的间隔。

对话/AI 聊天组件（严格对齐 Semi Chat）：DOM 对齐 Semi 结构 .cd-chat > -inner > -content > -container；消息流（Avatar 头像/标题/内容 MarkdownRender/操作区 Button+具名图标）+ 输入区（-inputBox > -inner > -clearButton + -container(-upload/-inputArea TextArea/-sendButton)）+ 提示区（-hints > -hint-item）。头像用本库 Avatar，操作/发送/上传/清除/回到底部/停止用本库 Button + 具名图标（copy=IconCopyStroked/like=IconLikeThumb·IconThumbUpStroked/reset=IconRedoStroked/delete=IconDeleteStroked/backBottom=IconChevronDown/stop=IconDisc/send=IconArrowUp旋转/upload=IconChainStroked/clear=IconDeleteStroked，对齐 Semi 非手写 svg）。loading 三点 flashing 动画。tokens 镜像 Semi variables.scss（~115 个）。框架无关逻辑在 @chenzy-design/core（buildSendContent/appendDivider/toggleLike/toggleDislike/resetLastMessage/shouldShowBackBottom/resolveEnableUpload/shouldSendOnEnter）。受控/非受控 chats，变换经 onChatsChange 回传。align(leftRight/leftAlign)、mode(bubble/noBubble/userBubble)、sendHotKey(enter/shift+enter)、enableUpload 三态、拖拽 dropArea。消息流 role=log/aria-live=polite；滚动出现回到底部悬浮按钮（SHOW_SCROLL_GAP=100）。ref 方法 resetMessage/scrollToBottom(animation)/clearContext/sendMessage。自定义渲染走 Svelte snippet（renderInputArea/renderChatBoxAvatar/Title/Content/Action/renderFullChatBox/renderHintBox/renderDivider）。

代码语法高亮：底层用 prismjs（严格对齐 Semi Design），DOM = div.cd-code-highlight(cd-light-scrollbar)[.cd-code-highlight-defaultTheme] > pre > code（根 class 顺序对齐 Semi：外部 class 在前）；给 <code> 元素加 language-<lang> class 后 Prism.highlightElement 就地高亮，仅写纯文本节点规避 XSS（不用 {@html} 拼未处理内容）。支持 lineNumber 行号、defaultTheme 内置配色开关（Semi 固定 dabblet 配色，写死色值 + 色板阶梯，非 token 驱动、不随明暗自适应，与 Semi 一致）。语言包按需由使用方 import "prismjs/components/prism-<lang>.js"。根节点无 role/aria-label/tabindex（Semi 源码无此增强，严格对齐不加）。无组件级 token（对齐 Semi 空 variables.scss）。

Markdown 渲染组件（严格对齐 Semi markdownRender，用 unified 管线替代 MDX）：remark-parse + 条件 remark-gfm + remark-rehype + 透传 remark/rehype 插件把 raw 编译成 hast，再由 Svelte 递归渲染。默认组件映射对齐 Semi 11 键（h1.tsx~h6.tsx/a.tsx/img.tsx/table.tsx/p.tsx/code.tsx 逐文件对应本库 h1.svelte~h6.svelte/a.svelte/img.svelte/table.svelte/p.svelte/code.svelte）：h1-h6→Typography.Title（cd-markdown-render-component-header）、p→Typography.Paragraph（-component-p）、a→Typography.Text link、img→div.-component-image>Image+alt、table→Table、code→同一组件按 className 是否含 language-* 分流（有→CodeHighlight lineNumber，无→span.-simple-code，行内 code 与无语言围栏代码块共用该分支）。不覆盖 pre（Semi 无此键，围栏代码块最终 DOM 是原生 <pre> 包裹 CodeHighlight/span）。标题字号/行高/颜色由 Typography 承担（Semi 亦然），组件只补 Semi 定义的 margin/simpleCode/image 样式（21 token 镜像 Semi variables.scss）。支持 components 覆盖；默认剥离 raw HTML（对齐 Semi format=md，保留需自传 rehype-raw 自负 XSS）。不支持 md 正文里任意 JSX 表达式求值（Semi format=mdx 深度能力，Svelte 无 jsx-runtime，运行时模型硬不兼容）。

通用拖拽移动容器（严格对齐 Semi Design dragMove，纯逻辑组件无样式层）：包裹单个子元素使其可被拖拽在页面/约束区内自由移动（与 Resizable 改尺寸正交，DragMove 改位置）。core 沉淀通用拖拽原语 createDragMove（命令式绑/解全局监听，pointerdown 记录起点→document 绑 move/up→计算 clamp 到 constrainer 的 top/left→rAF 内 customMove 或写 style→up 解绑+卸载兜底），供 Modal 可拖拽标题栏、Cropper 画布拖拽后续复用。init 强制 element position:absolute + handler cursor:move（对齐 Semi foundation）。约束区支持 parent/自定义 DOM/无约束；allowMove 谓词拦截；allowInputDrag 控制是否从表单元素发起。鼠标/触摸双通道，preventDefault 阻止文字选中与触屏滚动冲突（对齐 Semi，不用 CSS touch-action/user-select 兜底）。无 token/scss/className（对齐 Semi）；Svelte 无 cloneElement 故用一层透明 wrapper 承载几何（框架必要适配）。

JSON 预览 / 编辑器：底层直接引 Semi 自研框架无关内核 @douyinfe/semi-json-viewer-core（仿 VS Code text-buffer，虚拟化大数据、jsonc-parser 解析），内核经动态 import 异步加载（不进主 bundle，加载中 loading 态）。非受控（value 仅初始，不回写）。语法高亮全走 token（key/string/number/boolean·null/标点/注释/行号/搜索命中）深浅双主题。搜索/替换工具条由 Svelte 壳自渲染（内核仅提供检索 API），文案/aria 走 i18n。ref 暴露 getValue/format/search/getSearchResults/prevSearch/nextSearch/replace/replaceAll。options 支持 lineHeight/autoWrap/readOnly/customRenderRule（仅只读经 customRender 事件透出）/formatOptions。renderSearchButton 自定义搜索按钮（对齐 Semi ≥2.95）。

声明一组键盘快捷键组合并绑定 keydown 监听（默认全局 document.body，可局部），命中触发回调，并渲染键位提示（严格对齐 Semi：div.cd-hotKeys > span > span.-content + span.-split，用 span 非 kbd，键位原样渲染不做大小写/平台符号转换）。修饰键精确匹配 + 普通键用 event.code（物理键位，规避输入法/大小写，Semi 原生设计）。mergeMetaCtrl 为死 prop（严格对齐 Semi：声明但不生效，Meta/Ctrl 仍严格区分）。

在网页中展示 Lottie 动画，内部基于 lottie-web 渲染（严格对齐 Semi）。相较直接用 lottie-web，无需关心动画容器的创建与销毁、动画本身的生命周期。params 透传 lottie.loadAnimation（path CDN / animationData 打包 / renderer / loop / autoplay / container 等）；getAnimationInstance 获取当前 AnimationItem（含 play/pause/setSpeed 等方法）实现播放控制；getLottie 获取全局 lottie 包，亦可用静态方法 Lottie.getLottie()。params.container 存在时组件不渲染 DOM（用户自管容器）。

基于原生 <audio> 的音频播放器（严格对齐 Semi，无第三方媒体库）。audioUrl 接受 string | AudioInfo | (string|AudioInfo)[] 四形态；数组时启用播放列表（上/下曲、ended 自动切下一曲、取模循环连播）。工具栏含音量(Popover 竖向 slider)、快退/快进(按 skipDuration)、倍速(Dropdown 5 档 0.5/0.75/1/1.5/2)、刷新；播放控制含上/下曲(多曲)+播放/暂停(圆形)。进度/音量用自建 AudioSlider(hover 变粗+拖拽圆点+Tooltip 时间预览)。深/浅双主题(默认 dark)。静音切换 0↔50%(照搬 Semi)。

视频播放器：原生 <video> + 框架无关状态机（@chenzy-design/core），无第三方媒体库，严格对齐 Semi VideoPlayer。DOM 镜像 Semi（cd-videoPlayer 驼峰前缀：wrapper/video + poster img + 中央播放键 IconPlayCircle + ErrorSvg 插画 + notification + controls(VideoProgress + menu-left/right)）。复用 Button/Popover/Dropdown/AudioSlider + 11 具名图标。支持播放/暂停、进度拖拽跳转（含章节 markers 多段+缓冲/已播放双层+hover 放大+Tooltip 预览）、音量（Popover 竖向 AudioSlider，0–100 静音派生 0↔50）、倍率/清晰度/线路 Dropdown 切换（切后回跳原播放位置）、镜像、画中画、全屏、瞬时通知。controlsList 控制控件增删，theme 仅切换容器背景。键盘：Space 播放/暂停、←/→ 按 seekTime 跳转（焦点在播放器内时）。照搬 Semi 缺陷：clickToPlay 死 prop、next 控件绑 play/pause、硬编码色、音量键盘不实现；不复刻 Semi keydown 泄漏 bug。

输入联想框，data 由用户按 query 准备（远程或本地），支持键盘选择、内嵌标签与关键词高亮。

级联选择器，点击（或 hover）逐级展开列，单选叶子/任一层级；支持 multiple 多选（每列 checkbox + 父子联动 + 多 tag 回显）、可搜索过滤（本地/远程 + 结果虚拟滚动）、动态加载子节点、自定义字段映射与触发器/结果渲染。

多选框，可独立使用或置于 CheckboxGroup 中管理一组选项，支持半选态。

颜色选择器：严格对齐 Semi。inline 直接渲染选色面板（saturation 方块 + hue 条 + alpha 条 + DataPart 输入区），usePopover 时包裹浮层。值为 Semi ColorValue 对象 { hsva, rgba, hex }，经 onChange 通信。

日期选择器（对齐 Semi 单组件 + 7 值 type 枚举）：type ∈ date/dateRange/year/month/monthRange/dateTime/dateTimeRange。range 类型渲染双面板 + 起止双输入框触发器（rangeInputFocus 焦点驱动、自动排序、跨面板 hover 预览区间），受控/非受控；显示与星期/月份/年份均经 Intl.DateTimeFormat 本地化。支持 multiple 多选（仅 date，value 为 Date[]、max 上限）、presets 快捷选项（可置四向）、format token 串使触发器变可输入文本框、disabledDate/disabledTime 禁用、startDateOffset/endDateOffset 周选择、syncSwitchMonth 双面板同步翻月、timePickerOpts 透传、密度/无边框/自定义单元格与触发器渲染、面板四向 slot。

表单容器，桥接 headless createForm，提供字段注册、校验、布局与 a11y。

单行文本录入框，支持前后缀、前后置标签、清除、密码显隐与 IME。严格对齐 Semi。配套 TextArea（多行）与 InputGroup（组合），对齐 Semi 同页三组件（Input / TextArea / InputGroup 均为顶层导出）。

受约束的数值录入框，含步进按钮、键盘步进、精度与范围 clamp、货币/科学计数法展示。严格对齐 Semi。

分格验证码 / OTP 输入组件：N 个受控单字符输入格，逐格填入、自动跳格、整串粘贴自动分发，支持数字/混合/RegExp/函数四种字符校验。

单选框，通常置于 RadioGroup 中，遵循 WAI-ARIA radiogroup 模式（roving tabindex + 方向键）。

评分组件（对齐 Semi）：支持半星、hover 预览、点击清零与键盘操作；每颗星为 role=radio 双层（roving tabindex），额外空评分项承载 0 分焦点。

下拉选择器，支持单选 / 多选 / 本地过滤 / 键盘导航 / 浮层。

在连续/离散区间内选值的滑块，支持单值与 range、刻度、垂直方向与全键盘操作。严格对齐 Semi。

开关选择器，表示两种互斥状态的即时切换，支持加载态与自定义文案。

标签输入框，复用 Tag 渲染标签，支持回车 / 分隔符提交、退格删除、去重、上限与失焦提交。

时间选择器，严格对齐 Semi。触发器复用 Input（可键入时间串），面板复用 ScrollList/ScrollItem 滚动列。单选 type=time（HH:mm:ss 三列，+12h AM/PM 列），type=timeRange 左右双列并排选起止。format 字符串决定显示列与 12h（含 ss 即显示秒列）。

穿梭框，双栏列表间移动条目，严格对齐 Semi Design。单态模型：左侧勾选=立即迁移到右侧，无中间移动按钮。支持多选、本地/自定义/远程搜索、分组（groupList）、树状源面板（treeList，内嵌复用 Tree 组件）、左侧分页、右侧拖拽重排（draggable）与右侧虚拟化（virtualize）。

树形选择器，单面板可展开/收起的树，单选叶子或任意节点；支持 multiple 多选（checkbox + 父子联动 + 多 tag 回显）、可搜索过滤（本地/远程 + 命中高亮）、异步加载子节点、虚拟滚动大数据树、keyMaps 自定义字段映射与节点/tag/触发器渲染。严格对齐 Semi。

文件上传，严格对齐 Semi Design：点击/拖拽选择、文件卡片列表（list）与照片墙（picture）、真实 XHR 上传、裁切、目录上传。

锚点导航，垂直链接列表。组合式 API：children + <Anchor.Link>（对齐 Semi，无 links 数组 prop）。支持 scroll-spy 激活高亮、点击平滑滚动、滑轨条随激活项定位、自定义滚动容器、多级嵌套、文字缩略 Tooltip、autoCollapse 动态展开。

回到顶部悬浮按钮：滚动超过 visibilityHeight(默认 400px) 时显现、点击平滑缓动(easeInOutCubic, duration 默认 450ms)滚回顶部；默认监听 window，可经 target 指定自定义滚动容器；默认渲染 IconButton(theme="light") + IconChevronUp，可用 children 完全自定义。严格对齐 Semi。

面包屑导航，展示当前页面在层级结构中的位置。字段/API/DOM/class 严格对齐 Semi semi-ui/breadcrumb（index.tsx + item.tsx + bread-context.tsx 三文件拆分同构）。routes 元素为 Route 对象（{name, path, href, icon}）或纯字符串。支持数据驱动 routes 与声明式 Item 两种用法。icon/separator/renderItem/renderMore 均为组件引用直传（非 Snippet：Svelte 5 运行时无法可靠区分 Snippet 与裸 Component，见 Item.svelte 头注释）。

站点导航菜单（对齐 Semi Navigation）。支持垂直/水平模式、子导航（内联/浮层）、logo 头部、折叠按钮、多选。独立渲染，字段/回调对齐 Semi（itemKey/text/icon/items）。

分页器，用于切换大量数据的页码。严格对齐 Semi Design：default（完整页码 + 省略号折叠，7 格上限）与 small（current/total 紧凑视图，可 hoverShowPageSelect 悬停弹全部页码切页）两类布局。showTotal 显示总页数；省略号 hover 弹出隐藏页码。越界的当前页/每页条数与快速跳页输入均会被钳制到有效范围（纯函数实现，受控 prop 仅经回调上报）。

步骤条，引导用户按流程完成任务。组合式 API（<Steps><Steps.Step/></Steps>），严格全量对齐 Semi Design：文件结构（basicStep/basicSteps/fillStep/fillSteps/navStep/navSteps）、物理属性 CSS、具名图标、fill 型 Row/Col 栅格与三型差异化 props 边界均逐一对齐；纯受控 current（无 defaultCurrent）。

标签页，在同一区域内组织并切换多组对等内容。全量对齐 Semi Design：支持 line/card/button/slash 类型、top/left 位置、small/medium/large 尺寸、数据驱动 tabList 或纯声明式 <Tabs.Pane> 自动收集、renderTabBar 自定义标签栏、roving tabindex 键盘导航、可关闭标签、more 收纳与 collapsible 滚动折叠（含 auto 自动检测）。

树形控件（严格对齐 Semi）：层级展示节点，支持展开/收起、单选/多选（multiple 驱动 checkbox 父子联动含半选 mixed）、内置搜索高亮。值通道统一走 value/onChange。受控 value/expandedKeys 均不回写，仅通过 onChange/onExpand/onSelect/onSearch 通知。键盘导航遵循 WAI-ARIA APG Tree View（单一 tab stop + aria-activedescendant）。

头像：支持图片(src/srcSet)、加载失败降级到 children/alt 首字，circle/square 形状，7 档尺寸(默认 medium)或自定义 width，16 档语义色 + white(默认 grey)，字符按 gap 自适应缩放，hoverMask 悬浮遮罩，topSlot/bottomSlot 对象配置的顶部/底部标记，border 额外描边环 + contentMotion 内容动效。Avatar.Group 把多个头像层叠排列，maxCount 折叠出「+N」溢出头像，overlapFrom 控制压盖方向，组级 shape/size 强制下发(对齐 Semi cloneElement)。

徽标：在宿主元素角落展示 count 数字/dot 小圆点/自定义节点；无 children 时可独立使用。支持 type/theme/position/overflowCount。

纯事件展示日历，对齐 Semi Design Calendar。四视图 mode=day/week/month/range：day 单日时间轴（左时间列 + 单日列，25×2 半小时可点击格 + 绝对定位事件）；week 星期表头 + 7 列 DayCol，跨天事件走顶部全天区（parseWeekSpanEvents）；range 结构同 week，列数=range 天数（左闭右开），跨天走 parseSpanEvents；month 网格行数按 getWeeksInMonth 动态算（4/5/6 周皆有可能，非固定 6 周），跨天条走 getMonthEvents，每格超额显示「还有 N 项」并用 Popover 弹卡片（含关闭按钮）。displayValue 决定展示锚点；onClick 回调点击的精确时间点（日/周精确到半小时，月精确到日）。showCurrTime 当前时间红线（当天列，每 30s 刷新）。事件定位全部来自 @chenzy-design/core 纯算法（getDailyEvents/parseWeekSpanEvents/parseSpanEvents/getMonthEvents/calcRowHeight/allDayEventMap/getPos），本组件只把数值位置转成内联样式。事件外观由 event.children 承载（字符串直出 / snippet render），对齐 Semi children。头部对齐 Semi：无默认导航，仅当传入 header 时渲染自定义头部。

卡片容器：header(headerExtraContent + title，或 header 覆盖) → cover(出血) → body(children，loading 时 Skeleton 占位 + actions 底部操作) → footer。bordered/shadows 控制视觉；string title 用 Typography.Title heading=6 渲染并经 aria-labelledby 关联。

走马灯：多张幻灯片轮流播放。支持 slide/fade 切换动画、autoPlay 自动播放（含 interval/hoverToPause）、dot/line/columnar 指示器（位置 left/center/right，尺寸 small/medium）、prev/next 箭头（always/hover）、自定义箭头 arrowProps、primary/light/dark 主题、受控 activeIndex 与 onChange。slide 通过 Snippet[] 传入。DOM 结构、tokens、动画逐项对齐 Semi。

折叠面板，可展开或折叠展示内容区域。用 <Collapse.Panel itemKey header> 声明面板，支持受控 activeKey、accordion 手风琴、clickHeaderToExpand、自定义 expandIcon/collapseIcon、keepDOM/lazyRender、展开动画。DOM/API/tokens 对齐 Semi。

折叠容器原语：对任意内容做高度折叠/展开过渡，无触发器 UI（aria-expanded 由使用方提供）。是 Collapse 手风琴的底层能力，作为独立原语暴露以支持 keepDOM / lazyRender / collapseHeight 等精细控制。机制镜像 Semi：ResizeObserver 测内容高度 + wrapper 显式 height 过渡，仅过渡进行中挂载 transition class。

描述列表，用于键值对的成组呈现。镜像 Semi Design：table 语义结构，data 数据驱动与 <Descriptions.Item> 声明式两种用法；align（center/justify/left/plain）四种对齐；layout（vertical/horizontal）+ column 每行列数；row 双行显示（small/medium/large）；keyStyle 自定义 key 样式；value 支持字符串或富内容 Snippet。

向下弹出的菜单，通过触发元素唤起一组可操作命令项。对齐 Semi：children 为触发器，render/menu 定义浮层内容（Dropdown.Menu/Item/Title/Divider）；hover/focus/click/custom/contextMenu 触发；12 方位；嵌套子菜单（手动嵌套 Dropdown）；showTick 勾选、type 五色语义、icon、active、disabled；键盘导航与 Esc 关闭。

空状态占位。镜像 Semi Design：image / darkModeImage 接受插画节点(imageSlot)、SVG 精灵对象 { id, viewBox, url } 或图片 URL 字符串；darkModeImage 存在时监听 data-theme 在暗色下切换插画；title 用 Typography.Title（有图 heading=4，无图 heading=6+字重 400）；description 为 div；layout 支持 vertical / horizontal。插画由独立 illustrations 资产提供（对齐 @douyinfe/semi-illustrations）。

纯展示文本高亮：在 sourceString 中标记 searchWords，命中片段默认用 <mark> 包裹。纯文本输出（HTML 会被转义而非解析），支持大小写敏感、正则转义开关、自定义包裹元素/类名/样式，以及对象数组差异化样式（不同关键词单独 className/style）。

图片：加载态机（loading 骨架/自定义占位 → success → error 降级图/自定义/默认破图），success 且 preview 时 hover 蒙层 + 点击进全屏预览。预览浮层（ImagePreview）对齐 Semi：底部工具栏含上一张/页码/下一张、缩放 Slider、放大/缩小、原始尺寸↔适应页面切换、旋转、下载，支持鼠标滚轮以指针为锚缩放、超出容器拖拽平移、无限循环、预加载、无操作自动隐藏工具栏、renderHeader/renderPreviewMenu(menuItems)/renderCloseIcon/renderLeftIcon/renderRightIcon 自定义槽。ImagePreview 既可包裹多个 <Image> 做组预览，也可独立传 src 编程式控制。

图片裁切：容器 + 底图 + 遮罩 + 裁切框（含裁切视图 + 8 resize 角点）。几何逻辑委托 @chenzy-design/core 的 CropperFoundation（框架无关，纯原生 DOM/canvas，不引第三方）。支持 rect/round/roundRect 三形状、aspectRatio 比例约束、8 角点自由/约束 resize、裁切框拖拽、遮罩拖拽移动底图、滚轮以指针为中心缩放（min/max/step 钳制）、受控 rotate/zoom、容器 resize 重排、preview 实时预览、getCropperCanvas() ref 取裁切结果 canvas。受控 aspectRatio/rotate/zoom 只读不回写，onZoomChange 仅通知。

列表：数据驱动渲染（dataSource + renderItem）或声明式内嵌 <List.Item>，支持 header/footer（string 或 Snippet）、bordered 外框、split 分隔线、layout（vertical/horizontal）、grid 栅格（复用 Row/Col）、loading（复用 Spin）与空态（缺省 locale emptyText）。严格镜像 Semi List API。

模态对话框，严格镜像 Semi Design。DOM：.cd-modal-fixed > .cd-modal-mask + .cd-modal-wrap(role=none 滚动/遮罩点击) > .cd-modal(尺寸壳) > .cd-modal-content(role=dialog aria-modal)。API 对齐 Semi 名：visible/closeOnEsc/getPopupContainer/afterClose/motion/okType(5 种)/size(small|medium|large|full-width)/header(Snippet)/footerFill 等。关闭按钮用 IconButton + IconClose（@chenzy-design/icons），标题用 Typography.Title heading=5。受控 visible 不回写，仅 onVisibleChange/onCancel 通知。命令式工厂 Modal.confirm/info/success/warning/error（异步 onOk 自动 loading）+ Modal.destroyAll + Modal.useModal（配合 ModalContextHolder 继承 context）。可拖拽经 modalRender + DragMove（对齐 Semi）。堆叠 z-index 由模块级计数器分配（声明式与命令式共享）。

溢出折叠列表，严格镜像 Semi OverflowList。行为组件：展示列表并自适应展示尽可能多的项目，因过长而溢出的项折叠为一个元素，容器 resize 时重新计算可见项。renderMode="collapse"（默认）用 ResizeObserver 累加各项宽度找折叠点，溢出项收纳进 overflowRenderer 返回的节点，collapseFrom 决定从尾（end）/头（start）折叠，minVisibleItems 保底可见数；renderMode="scroll" 不折叠，可见层为可横向滚动容器，用 IntersectionObserver 观测各项，threshold 控制阈值，onIntersect/onVisibleStateChange 上报可见状态。渲染函数以 Svelte Snippet 形式提供（visibleItemRenderer/overflowRenderer）。

气泡卡片，点击/悬停/聚焦触发元素时弹出富内容浮层。封装 Tooltip（对齐 Semi 继承链），支持标题、12 方位 position、SVG 箭头、间距、custom 完全受控与 condition 条件触发，浮层命令式定位。

滚动列表，类似 iOS 的滚动选择模式。ScrollList 是纯容器（header/footer/bodyHeight），内部放若干 ScrollItem 组成多列。ScrollItem 有 wheel（滚轮，滚动/点击将候选吸附到中央选区居中）与 normal（普通列表，点击选中并高亮）两种模式；wheel 支持 cycled 无限循环、motion 缓动、transform 选中项文案变换、disabled 跳过。选择通过 selectedIndex 受控 + onSelect(data) 回调（data 含 value/index/type）。复用 @chenzy-design/core 纯函数（resolveItemText/centerOffset/nearestIndex/wrapIndex/scrollFrame/shouldPrepend/shouldAppend）。

滑动侧边栏：从视口四边（left/right/top/bottom）滑入的浮层容器，承载二级操作页面 / 详情 / 表单 / 筛选，比 Modal 提供更大可滚动内容区。DOM 结构与类名严格对齐 Semi：wrapper(.cd-sidesheet-{placement}) > mask + inner(.cd-sidesheet-inner.cd-sidesheet-inner-wrap.cd-sidesheet-size-{size}, role=dialog tabindex=-1) > content > header(role=heading aria-level=1)+body+footer。Portal 到 getPopupContainer()/body 脱离父层叠上下文；role=dialog，mask 时加 aria-modal；closeOnEsc（默认 false）时 window 监听 Esc 关闭；mask=true 默认锁 body 滚动（disableScroll），getPopupContainer 指向非 body 时为 popup 模式（wrapper position:static）。mask=false 为可操作外部区域形态（无遮罩、面板 box-shadow: --cd-shadow-elevated、宽度落在 wrapper）。size(small448/medium684/large920，默认 small) 仅 left/right 生效；width（默认 448，left/right）/ height（默认 448，top/bottom）显式覆盖。进出场动画对齐 Semi CSSAnimation：mask 淡入淡出 + inner 按 placement 滑入滑出，animationend 后卸载；motion=false 或 prefers-reduced-motion 退化即时显隐。关闭按钮用 IconButton（type=tertiary theme=borderless size=small）+ IconClose。受控 visible（不回写），仅经 onCancel(e) 通知；afterVisibleChange 于动画结束回调可见状态。keepDOM 关闭保留 DOM。

表格：列定义驱动渲染，三态排序(升/降/无)、客户端分页、行选择(含半选 indeterminate)；sortState / rowSelection.selectedRowKeys / pagination.currentPage 受控不回写，仅经 onSortChange / onChange 通知。复用 @chenzy-design/core 纯函数算法与 Pagination 组件。支持行展开：expandedRowRender / rowExpandable / expandedRowKeys / defaultExpandedRowKeys / onExpand / onExpandedRowsChange 均为顶层 prop（对齐 Semi Table.tsx 单一顶层架构，无 expandable/tree 嵌套状态对象）。固定列 fixed、列筛选 filters/onFilter、列宽拖拽 resizable（本地覆盖宽度不写回 columns）。树形数据 tree=true（行含 childrenRecordName 字段嵌套，第一列展开三角+缩进，排序/分页作用于顶层行，扁平化用 core flattenTreeRows 纯函数）；与 expandedRowRender 共用同一份 expandedRowKeys 状态与展开图标机制，受控展开 keys 不回写，仅经 onExpand(单行)/onExpandedRowsChange(全量展开记录数组) 通知。树形行选择父子联动 rowSelection.checkStrictly（默认 false 勾父连带后代+半选，true 父子独立；联动用 core conductRows/toggleRowCheck 纯函数）。行虚拟滚动 virtualized：仅渲染视口内行切片（复用 core fixedRange），首尾 padding spacer tr 撑总高，保持原生 table 语义；thead sticky 固定顶部；与 pagination 互斥（虚拟时忽略分页）。

标签：light/solid/ghost 三态，16 色板 + white，可关闭(closable)、可交互(onClick/keydown)、头像(avatarSrc)、AI 多彩(colorful/gradient)、前后缀图标。受控 visible 不回写，仅通过 onClose 通知。配套 TagGroup（折叠 +N）与 SplitTagGroup（连接式组合），对齐 Semi 同页三组件。

时间轴，用于对一系列信息进行时间排序时垂直展示。两种用法择一：传 dataSource 数据驱动（支持 content 属性及 Timeline.Item 全部属性），或在 children 内写 <Timeline.Item> 声明式。通过 mode 设置时间轴与内容的相对位置：left（默认）/right/center/alternate。

文字提示，鼠标悬停/聚焦/点击/右键触发元素时展示简短说明。固定深色浮层（grey-7），DOM 严格对齐 Semi：.cd-tooltip-wrapper[x-placement] > .cd-tooltip-content + 单 path 箭头 .cd-tooltip-icon-arrow（fill=currentColor）。支持 12 方位 position、hover/focus/click/custom/contextMenu 触发、延迟、custom 完全受控、condition 条件触发，浮层命令式定位（对齐 Semi）。prefixCls 机制供 Popover/Popconfirm 复用切换前缀。

用户引导：popup 模式复用本库 Popover（trigger="custom"）贴气泡讲解 + svg mask 挖洞 spotlight 遮罩逐个高亮目标元素（4 块透明 rect 让高亮区可交互，目标不在视口时 scrollIntoView）；modal 模式复用本库 Modal（header/footer=null、centered、bodyStyle padding:0）图文引导（cover 封面 + 圆点指示器）。步进状态机在 core createUserGuide：current 受控（提供 current 即受控，内部不改需配合 onChange 回写）/非受控，handlePrev/handleNext/handleSkip 回调去重（current 未变不 notify onChange），末步 handleNext 触发 onFinish，visible false→true 重置 current=0 并锁 body 滚动（getPopupContainer 时跳过、补偿滚动条宽），按钮显隐规则（跳过=非末步、上一步=非首步、下一步/完成）。指示器 popup 为纯文本 n/total（对齐 Semi 无 i18n），modal 为圆点。onFinish/onSkip 不自动关闭，使用方置 visible=false。严格对齐 Semi：无 focus-trap/inert/Esc/箭头键/进度 aria/live-announcer。

虚拟滚动列表底座（泛型）：仅渲染可视区 + overscan 缓冲区高性能渲染超长列表。fixed 定高 O(1) 区间；dynamic 不定高（itemSize='auto'）用 estimatedItemSize 估算 + ResizeObserver 实测回填高度表，前缀和修正偏移/区间并做滚动偏移补偿。支持 vertical/horizontal（horizontal 仅 fixed 定宽，dynamic 退化为按 estimatedItemSize 的定宽）。scrollTarget='self'（默认）内部容器滚动；'window' 用窗口（document）滚动、容器撑高，适合整页长列表（纵向；horizontal 下退化为 self，fixed/dynamic 均复用窗口几何 windowScrollTop）。提供 scrollToIndex 命令式跳转 API。自身无视觉，行渲染由 renderItem 提供。

通知横幅：横幅通常用于标识全页的状态或通知等，常驻并由用户主动关闭。支持 info / success / danger / warning 四语义，fullMode 全屏与非全屏（可 bordered 边框）两形态；title / description / icon / closeIcon 可自定义，children 渲染于尾部 extra 区。role="alert"，关闭按钮可 Tab + Enter/Space。

通知提醒框：命令式全局反馈 API（notification.open/success/info/warning/error/close/destroyAll/config + useNotification）。严格对齐 Semi——标题 + 内容 + 图标；六方位独立堆叠；单例容器惰性挂载到 getPopupContainer()（默认 body）；duration 秒自动关闭（0 常驻）+ hover 暂停/重启定时器 + 同 id 原地更新；role=alert + aria-labelledby 关联标题；theme(normal/light) 填充样式；icon 自定义图标；onClick 点击回调；onCloseClick 关闭按钮回调；notification.config({ top/bottom/left/right/position/duration/zIndex/direction/getPopupContainer }) 全局配置（首次生效）。useNotification() 返回 [api, holderStore]，配合 <NotificationHolder store={holderStore}> 让通知继承组件树上下文。

用户反馈收集弹窗：以 SideSheet(popup) 或 Modal(modal) 形态收集 emoji 评分 / 文本 / 单选 / 多选 / 自定义反馈。纯组合本库 SideSheet/Modal + TextArea/RadioGroup/CheckboxGroup/Button。

气泡确认框：目标元素操作需二次确认时使用。封装 Popover，内置确认/取消双按钮 + 可选右上角关闭按钮，比 Modal 更轻量。支持 title/content（content 可为函数注入 initialFocusRef）、icon（缺省 IconAlertTriangle）、okType/cancelType、okButtonProps/cancelButtonProps（含 autoFocus）、onConfirm/onCancel 返回 Promise 时对应按钮 loading（resolve 关闭 / reject 保持）、12 方位 position（默认 bottomLeft）。role=dialog non-modal。

进度条：line（horizontal / vertical）与 circle 两形态；percent 钳制到 0..100，showInfo/format 控制信息区，stroke 支持字符串或分段颜色数组（配合 strokeGradient 渐变），orbitStroke 自定义轨道色，数字滚动线性动画；role=progressbar，受控 percent 不回写。

骨架屏：loading 切换占位/真实内容，active 开启 shimmer 流光动画；提供 Avatar / Image / Title / Button / Paragraph 五个原子占位形状自由组合。镜像 Semi：占位根节点为纯 <div class="cd-skeleton">，active 挂根容器类经后代选择器作用到骨架块。loading 受控不回写。

加载指示器，严格对齐 Semi Design：统一 DOM（.cd-spin > .cd-spin-wrapper 指示器 + .cd-spin-children 内容），有 children 时块级包裹并遮罩内容（opacity 0.5、不可交互），无 children 时独立指示器。delay 延迟去抖（复用 @chenzy-design/core createSpinController，无 minShowTime）。role=status + aria-live=polite 公布加载，装饰 SVG aria-hidden，reduced-motion 退化为呼吸。spinning 受控不回写。

轻提示：命令式全局反馈 API（Toast.info/success/warning/error/close/destroyAll/config/useToast + ToastFactory.create），严格对齐 Semi Design。单例容器惰性挂载到 body（wrapper 固定顶部居中，config 的 top/left/bottom/right 整体偏移）；type=info/success/warning/error/default（default 无内置图标）；theme=normal（白）/light（多色填充+描边）；stack 多条堆叠、Hover 展开（3D 透视折叠）；duration 自动关闭（0 常驻）、mouseenter 暂停/mouseleave 从头计时；showClose 关闭按钮（复用 IconButton）；textMaxWidth 内容最大宽度；content/icon 支持 string 或 Snippet；对已存在 id 再调 info/success 即原地更新。useToast() 返回 [api, holderStore]（含 info/success/warning/error/open/close，open 展示 type=default 的 toast，对齐 Semi 该方法仅存在于 useToast，顶层 Toast 无 open）经 <ToastHolder> 渲染在组件树内继承上下文；ToastFactory.create(config) 创建带独立 config 的新实例（如 getPopupContainer）。a11y：卡片 role=alert + aria-label="{type} type"（对齐 Semi），关闭按钮 IconButton 带可访问名。

全局配置总入口，借助 Svelte Context 向子树注入跨组件公共配置：locale（多语言，复用 LocaleProvider 的 createLocale + LOCALE_CONTEXT_KEY 机制注入）、direction（文本方向，rtl 时渲染 `<div class="cd-rtl">` 包裹层驱动组件镜像，否则 renderless 无 DOM）、timeZone（时区标识，数字偏移 / GMT± / IANA，透传给时间类组件）、getPopupContainer（全局浮层默认挂载容器，经 context 暴露给浮层组件在自身 prop 未传时回退，最终回退 document.body）。嵌套时浅合并（undefined 继承、就近 wins）。响应式断点：responsiveObserve 默认 false（不注册任何 matchMedia），开启后在首次订阅时懒注册监听、无订阅时自动注销；responsiveMap 自定义断点（key 为 xs/sm/md/lg/xl/xxl，引用比较，inline 新对象触发重注册）；onBreakpoint / screens 非 props，经 getConfigResponsive（等价 Semi ConfigConsumer）读取，onBreakpoint 支持 `(cb)`（拿完整 screens）与 `(breakpoints, cb)`（拿单断点变化）两种签名、订阅时立即回调一次；defaultResponsiveMap 作为默认断点导出。ConfigProvider 本身无独立 token / scss，是纯逻辑组件（对齐 Semi）。

语言上下文注入组件，renderless 无 DOM 输出。严格对齐 Semi locale/localeProvider.tsx：唯一 prop 是 locale，通过 setContext 把解析后的 LocaleApi 原样注入子树，不做深合并/方向推断/时区货币继承/变更回调——这些能力在 Semi 里也不存在（Semi 只把 locale 对象透传给消费组件，格式化逻辑在各消费组件内部）。locale 支持语言包对象或字符串码（registerLocale 注册表 + 内置查表解析，本库为语言包数量少于 Semi 而补充的能力）。

尺寸监听工具组件，封装原生 ResizeObserver（经 @chenzy-design/core 归一化），渲染一个无视觉样式的包裹元素作为观测容器，slot 暴露 width/height/entry，onResize 分发归一化尺寸事件；内置 throttle/debounce 节流去抖与 multiple 多目标观测；SSR/老浏览器静默降级，fallbackToWindow 可降级为 window.resize 近似监听；onResizeStart/onResizeEnd 暴露连续变化的首帧与静默结束边界事件；另导出 resize action 供轻量 use:resize 用法、getGlobalResizeObserver 单例池供大列表共享。盒模型支持 content-box/border-box/device-pixel-content-box，包裹元素标签可经 tag 自定义。