sparkdesign 0.4.5 → 0.4.7

package/dist/registry/basic/radio-group.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (RadioGroupProps, RadioGroupItemProps)
- * [OUTPUT]: (JSX.Element) - 单选按钮组组件
- * [POS]: registry/basic/radio-group - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/radio-group.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff radio-group 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';

package/dist/registry/basic/resizable.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (ResizablePanelGroupProps, ResizablePanelProps, ResizableHandleProps)
- * [OUTPUT]: (JSX.Element) - 可调整大小面板组件
- * [POS]: registry/basic/resizable - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/resizable.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff resizable 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import type { GroupProps, PanelProps, SeparatorProps } from 'react-resizable-panels';

package/dist/registry/basic/scroll-area.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import { ScrollArea as ScrollAreaPrimitive } from "radix-ui";
+declare function ScrollArea({ className, children, ...props }: React.ComponentProps<typeof ScrollAreaPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function ScrollBar({ className, orientation, ...props }: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>): import("react/jsx-runtime").JSX.Element;
+export { ScrollArea, ScrollBar };

package/dist/registry/basic/select.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (Select*Props)
- * [OUTPUT]: (JSX.Element) - 选择器组件
- * [POS]: registry/basic/select - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/select.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff select 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import * as SelectPrimitive from '@radix-ui/react-select';

package/dist/registry/basic/separator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * [WHO]: Separator — visual/semantic divider built on @radix-ui/react-separator.
+ * [FROM]: React + @radix-ui/react-separator + `@/lib/utils` cn.
+ * [TO]: sparkdesign package consumers; output of CLI `add separator` when registered.
+ * [HERE]: registry/basic/separator.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
+ */
+import * as React from 'react';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+export type SeparatorProps = React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>;
+declare const Separator: React.ForwardRefExoticComponent<Omit<SeparatorPrimitive.SeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export { Separator };

package/dist/registry/basic/sheet.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Sheet — compatibility alias for Drawer using shadcn-style naming.
+ * [FROM]: registry/basic/drawer.
+ * [TO]: sparkdesign package consumers; output of CLI `add sheet` when registered.
+ * [HERE]: registry/basic/sheet.tsx — Spark Design source; keep aligned with Drawer semantics.
+ *
+ * [PROTOCOL]:
+ * 1. Keep Sheet as a thin compatibility layer; Drawer remains the canonical semantic component.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
+ */
+export { Drawer as Sheet, DrawerTrigger as SheetTrigger, DrawerClose as SheetClose, DrawerPortal as SheetPortal, DrawerOverlay as SheetOverlay, DrawerContent as SheetContent, DrawerHeader as SheetHeader, DrawerFooter as SheetFooter, DrawerTitle as SheetTitle, DrawerDescription as SheetDescription, drawerVariants as sheetVariants, } from './drawer';
+export type { DrawerContentProps as SheetContentProps, DrawerHeaderProps as SheetHeaderProps, DrawerFooterProps as SheetFooterProps, } from './drawer';

package/dist/registry/basic/slider.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (SliderProps)
- * [OUTPUT]: (JSX.Element) - 滑块组件
- * [POS]: registry/basic/slider - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/slider.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff slider 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import * as SliderPrimitive from '@radix-ui/react-slider';

package/dist/registry/basic/sonner.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (ToasterProps) - sonner Toaster 配置，可选 dataStyle/dataTheme
- * [OUTPUT]: (JSX.Element) - Portal 到 body 的 Toast 容器，样式通过 design tokens
- * [POS]: registry/basic/sonner - Toaster 唯一来源；主库再导出并注入 useIcon、buttonVariants
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/sonner.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 修改样式时需同步更新 defaultToastOptions 中的 CSS 变量
- * 2. 主库组件从 registry 导入，注入 data-style/data-theme 上下文
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import type { ToasterProps as SonnerToasterProps } from 'sonner';

package/dist/registry/basic/switch.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (SwitchProps)
- * [OUTPUT]: (JSX.Element) - 开关组件（toggle only，无 segment 变体）
- * [POS]: registry/basic/switch - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/switch.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff switch 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import * as SwitchPrimitives from '@radix-ui/react-switch';

package/dist/registry/basic/tabs.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (Tabs*Props)
- * [OUTPUT]: (JSX.Element) - 标签页组件
- * [POS]: registry/basic/tabs - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/tabs.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff tabs 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import * as TabsPrimitive from '@radix-ui/react-tabs';

package/dist/registry/basic/tag.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (TagProps)
- * [OUTPUT]: (JSX.Element) - 标签/徽章组件
- * [POS]: registry/basic/tag - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/tag.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff tag 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';

package/dist/registry/basic/textarea.d.ts

@@ -0,0 +1,15 @@
+/**
+ * [WHO]: Textarea — multi-line text input with token-driven styling.
+ * [FROM]: React + `@/lib/utils` cn.
+ * [TO]: sparkdesign package consumers; output of CLI `add textarea` when registered.
+ * [HERE]: registry/basic/textarea.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
+ */
+import * as React from 'react';
+export type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>;
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+export { Textarea };

package/dist/registry/basic/theme-from-document.d.ts

@@ -1,10 +1,12 @@
 /**
- * [INPUT]: (N/A) - 从 document.documentElement 读取
- * [OUTPUT]: (Record<string, string>) - 包含 data-theme / data-style 属性
- * [POS]: registry/basic/theme-from-document - 注册表工具函数
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/theme-from-document.ts — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用于 Portal 根节点继承主题，无 Context 依赖
- * 2. 更新时使用 npx sparkdesign diff theme-from-document 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 export declare function getThemeFromDocument(): Record<string, string>;

package/dist/registry/basic/toggle.d.ts

@@ -3,7 +3,7 @@ import * as TogglePrimitive from '@radix-ui/react-toggle';
 import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';
 import { type VariantProps } from 'class-variance-authority';
 declare const toggleVariants: (props?: ({
-    variant?: "default" | "outline" | null | undefined;
+    variant?: "outline" | "default" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
     rounded?: "square" | "pill" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/registry/basic/tooltip.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (TooltipProps)
- * [OUTPUT]: (JSX.Element) - 工具提示组件
- * [POS]: registry/basic/tooltip - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/tooltip.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff tooltip 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';

package/dist/registry/basic/typography.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (Typography*Props)
- * [OUTPUT]: (JSX.Element) - 排版组件（H1–H4, P, Blockquote 等）
- * [POS]: registry/basic/typography - 注册表模板，复制到用户项目后可自由修改
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/basic/typography.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 用户可自由修改此文件
- * 2. 更新时使用 npx sparkdesign diff typography 查看差异
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import * as React from 'react';
 export type TypographyH1Props = React.ComponentProps<'h1'>;

package/dist/registry/chat/ask-user-part.d.ts

@@ -1,7 +1,13 @@
 /**
- * [INPUT]: (AskUserPartProps) - title、question、skipText/runText；可选 headerIcon，未指定则用内联 SVG
- * [OUTPUT]: (JSX.Element)
- * [POS]: registry/chat - AI 向用户询问确认的卡片组件
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/ask-user-part.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import type { ReactNode } from 'react';
 export interface AskUserPartProps {

package/dist/registry/chat/browser-action-part.d.ts

@@ -1,7 +1,13 @@
 /**
- * [INPUT]: (BrowserActionPartProps) - description、content、status；可选 normalIcon/failedIcon/skippedIcon，未指定则用内联 SVG
- * [OUTPUT]: (JSX.Element)
- * [POS]: registry/chat - AI Agent 浏览器操作卡片组件
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/browser-action-part.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import { type ReactNode } from 'react';
 export type BrowserActionStatus = 'normal' | 'failed' | 'skipped';

package/dist/registry/chat/chat-input/compound.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: 各复合组件的 props，或从 Context 消费
- * [OUTPUT]: ChatInput.Above / Box / Attachments / Input / Actions / ActionsLeft / ActionsRight / ExpandButton / FolderButton / MoreButton / SendButton / DefaultLayout
- * [POS]: registry/chat/chat-input - 四层结构复合组件，见 docs/ChatInput四层结构设计.md
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/chat-input/compound.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 所有子组件必须在 ChatInput.Root 内使用
- * 2. 布局与层级与设计文档一一对应
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import React from 'react';
 import type { ReactNode } from 'react';

package/dist/registry/chat/chat-input/context.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (ChatInputContextValue) - 由 Root 注入
- * [OUTPUT]: Context + Provider + Hook
- * [POS]: registry/chat/chat-input - 复合组件共享状态
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/chat-input/context.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 仅被 Root 与复合子组件使用
- * 2. 新增/删除状态时同步更新 ChatInputContextValue 与 Root 中的初值
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import React from 'react';
 import type { ReactNode } from 'react';
@@ -17,6 +19,8 @@ export interface ChatInputContextValue {
     onChange: (value: string) => void;
     onSend?: (value: string) => void;
     disabled: boolean;
+    placeholder: string;
+    maxRows: number;
     form?: string;
     textareaRef: React.RefObject<HTMLTextAreaElement | null>;
     setTextareaRef: (node: HTMLTextAreaElement | null) => void;
@@ -57,7 +61,7 @@ export declare function useChatInputContext(): ChatInputContextValue;
 export type ChatInputRootProps = ChatInputProps & {
     children?: ReactNode;
 };
-export declare function ChatInputRootProvider({ value: controlledValue, onChange, onSend, placeholder, disabled, maxRows, form, sendButtonStatus, showFooter, showFolderButton, folderButtonLabel, onFolderButtonClick, onFolderClear, folderPermission, showMoreButton, onMoreButtonClick, footerLeftConfig, showGenerationStatus, generationStatus, attachments, addLargeIcon, folderIcon, folderOpenIcon, historyIcon, arrowDownIcon, subMenuArrowIcon, folderFillIcon, closeIcon, dataStyle, dataTheme, className, children, ...rest }: ChatInputRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatInputRootProvider({ value: controlledValue, onChange, onSend, placeholder, disabled, maxRows, form, sendButtonStatus, showFooter, showFolderButton, folderButtonLabel, onFolderButtonClick, onFolderClear, folderPermission, showMoreButton, onMoreButtonClick, footerLeftConfig, showGenerationStatus, generationStatus, attachments, addLargeIcon, folderIcon, folderOpenIcon, historyIcon, arrowDownIcon, subMenuArrowIcon, folderFillIcon, closeIcon, dataStyle, dataTheme, children, ...rest }: ChatInputRootProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ChatInputRootProvider {
     var displayName: string;
 }

package/dist/registry/chat/chat-input/index.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (ChatInputProps) 或 复合用法 ChatInputRoot + Above/Box/…（主 API）
- * [OUTPUT]: (JSX.Element)
- * [POS]: registry/chat/chat-input - 依赖 send-button, generation-status-bar, icon-button, 子组件
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/chat-input/index.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 主 API 为复合组件（Root/Above/Box/Input/Actions/SendButton 等）；ChatInput 仅为默认组合的便捷导出。
- * 2. 文件逻辑变更时同步更新 Header、types.ts；见 docs/ChatInput四层结构设计.md
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import React from 'react';
 import { ChatInputRootProvider } from './context';

package/dist/registry/chat/chat-input/types.d.ts

@@ -1,7 +1,13 @@
 /**
- * [INPUT]: 无
- * [OUTPUT]: 类型导出
- * [POS]: registry/chat/chat-input - ChatInput 类型定义
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/chat-input/types.ts — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import type { TextareaHTMLAttributes, ReactNode } from 'react';
 export type InputPropsWithWebkitDirectory = React.InputHTMLAttributes<HTMLInputElement> & {

package/dist/registry/chat/chat-input/useAutoResizeTextarea.d.ts

@@ -1,7 +1,13 @@
 /**
- * [INPUT]: (textareaRef, value, maxRows)
- * [OUTPUT]: void
- * [POS]: registry/chat/chat-input
+ * [WHO]: Output: void; Inputs: (textareaRef, value, maxRows)
+ * [FROM]: react
+ * [TO]: CLI `add` copy target; canonical implementation in `src/components`
+ * [HERE]: registry/chat/chat-input
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when behavior changes
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when needed
+ * 3. Follow repository conventions for tokens and exports
  */
 import { type RefObject } from 'react';
 export declare function useAutoResizeTextarea(textareaRef: RefObject<HTMLTextAreaElement | null>, value: string, maxRows: number): void;

package/dist/registry/chat/code-block-part.d.ts

@@ -1,7 +1,13 @@
 /**
- * [INPUT]: (CodeBlockPartProps) - language、code、filename、diffType、isGenerating；可选 headerIcon/getFileIcon
- * [OUTPUT]: (JSX.Element)
- * [POS]: registry/chat - 从 QodeChatPanel 移植，全 token 化；使用 Prism 语法高亮（设计令牌主题）
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/code-block-part.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import { type ReactNode } from 'react';
 export type CodeBlockDiffType = 'add' | 'remove';

package/dist/registry/chat/conversation-anchor-nav.d.ts

@@ -0,0 +1,72 @@
+import type { RefObject, ReactNode } from 'react';
+/** 单个锚点项 */
+export interface ConversationAnchorItem {
+    /** 稳定 id，用于定位 DOM 节点与 React key */
+    id: string;
+    /** 在 Tooltip 中展示的摘要文案（纯文本）。为空时回落到 labels.scrollTo。 */
+    summary?: string;
+}
+/** i18n 文案 */
+export interface ConversationAnchorLabels {
+    /** nav 的 aria-label */
+    ariaLabel?: string;
+    /** Tooltip 兜底文案（无摘要时） */
+    scrollTo?: string;
+}
+/** 样式变体 */
+export type ConversationAnchorVariant = 'bar' | 'punch';
+export interface ConversationAnchorNavProps {
+    /** 滚动容器 ref，用于检测当前可视锚点；受控场景可传 { current: null } */
+    scrollContainerRef: RefObject<HTMLElement | null>;
+    /** 锚点列表，顺序即视觉顺序 */
+    items: ConversationAnchorItem[];
+    /** 点击锚点时回调，参数为在 items 中的索引与对应 item */
+    onSelect: (index: number, item: ConversationAnchorItem) => void;
+    /**
+     * 当前高亮索引（受控）。
+     * 省略时组件内部会订阅 scrollContainerRef 的滚动并通过 IntersectionObserver 自动推导。
+     */
+    activeIndex?: number;
+    /**
+     * 锚点视觉样式：
+     * - 'bar' （默认）：短横杠，hover 时加长
+     * - 'punch'：圆形"打孔"点，适合羊皮纸 / 拟物风主题
+     */
+    variant?: ConversationAnchorVariant;
+    /** 少于该数量时隐藏整个 nav，默认 3 */
+    minItems?: number;
+    /** 外部强制隐藏（例如 compact 布局），默认 false */
+    hidden?: boolean;
+    /** 自定义 Tooltip / aria 文案 */
+    labels?: ConversationAnchorLabels;
+    /** 额外 className（会与默认定位 className 合并） */
+    className?: string;
+    /**
+     * 自定义锚点元素解析。默认通过
+     * `scrollContainerRef.current.querySelector('[data-spark-anchor="<id>"]')`
+     * 查找；需要业务在消息容器上添加该属性。
+     */
+    getAnchorElement?: (item: ConversationAnchorItem, index: number, container: HTMLElement) => HTMLElement | null;
+    /** 渲染 slot：自定义每个锚点的视觉表达，返回 null 时回落到内置样式 */
+    renderAnchor?: (ctx: {
+        item: ConversationAnchorItem;
+        index: number;
+        isActive: boolean;
+        variant: ConversationAnchorVariant;
+    }) => ReactNode;
+}
+export declare const ConversationAnchorNav: import("react").NamedExoticComponent<ConversationAnchorNavProps>;
+export interface UseVisibleAnchorIndexOptions {
+    scrollContainerRef: RefObject<HTMLElement | null>;
+    items: ConversationAnchorItem[];
+    /** 与 ConversationAnchorNav 同名 prop，默认按 `[data-spark-anchor="<id>"]` 查找 */
+    getAnchorElement?: ConversationAnchorNavProps['getAnchorElement'];
+    /** 为 false 时不订阅滚动，返回 0；用于受控场景 */
+    enabled?: boolean;
+}
+/**
+ * 订阅 scroll 容器内每个锚点元素的可见性，返回"最靠近顶部且仍可见"的锚点索引。
+ * - 容器必须可滚动（通常 overflow-y: auto），且锚点元素是其后代
+ * - 每个锚点需要能通过 `getAnchorElement` 解析到 HTMLElement
+ */
+export declare function useVisibleAnchorIndex({ scrollContainerRef, items, getAnchorElement, enabled, }: UseVisibleAnchorIndexOptions): number;

package/dist/registry/chat/file-attachment.d.ts

@@ -1,11 +1,13 @@
 /**
- * [INPUT]: (FileAttachmentProps) - filename、onRemove、icon / getFileIcon
- * [OUTPUT]: (JSX.Element) - 带左图标（文件类型）的可关闭 Tag 样式附件
- * [POS]: registry/chat - 唯一来源，主库再导出并注入 getFileIcon
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/file-attachment.tsx — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * - 仅依赖 registry ui（tag、icons-inline）；不依赖 useIcons
- * - 可选 getFileIcon(filename, className) 或 icon；不传则用 FileLine
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import type { HTMLAttributes, ReactNode } from 'react';
 export interface FileAttachmentProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {

package/dist/registry/chat/file-review-part.d.ts

@@ -1,8 +1,13 @@
 /**
- * [INPUT]: (FileReviewPartProps) - files、defaultExpanded；可选 headerIcon/acceptIcon/rejectIcon/getFileIcon
- * [OUTPUT]: (JSX.Element)
- * [POS]: registry/chat - 从 QodeChatPanel 移植，全 token 化；默认用 Seti 字体图标（需加载 qoder-seti.woff），hover 显示对号/错号
- * Seti 映射与逻辑与 QodeChatPanel FileReviewPart.jsx 内联保持一致，避免模块解析差异导致图形与后缀对不上。
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/file-review-part.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import { type ReactNode } from 'react';
 export interface FileReviewFile {

package/dist/registry/chat/generated-images-grid.d.ts

@@ -1,7 +1,13 @@
 /**
- * [INPUT]: (GeneratedImagesGridProps) - 多图网格
- * [OUTPUT]: (JSX.Element) - 会话流中多张生成图片的横排排列容器
- * [POS]: registry/chat - 唯一来源，无图标依赖
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/generated-images-grid.tsx — Spark Design source; keep aligned with the main library.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import type { ReactNode } from 'react';
 export interface GeneratedImagesGridProps {

package/dist/registry/chat/generation-status-bar.d.ts

@@ -1,9 +1,13 @@
 /**
- * [INPUT]: (GenerationStatusBarProps)
- * [OUTPUT]: (JSX.Element) - 生成状态条
- * [POS]: registry/chat - 唯一来源，无图标依赖
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: registry/chat/generation-status-bar.tsx — Spark Design source; keep aligned with the main library.
  *
- * [PROTOCOL]: 样式使用 design token（h-9、text-sm、px-3、rounded-t-xl），随 data-style 变化，与 ChatInputAbove 一致。
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
  */
 import type { ReactNode } from 'react';
 export interface GenerationStatusBarProps {