zilmate 1.7.8 → 1.8.0

package/.agents/skills/ai-elements/references/context.md

@@ -0,0 +1,126 @@
+# Context
+
+A compound component system for displaying AI model context window usage, token consumption, and cost estimation.
+
+The `Context` component provides a comprehensive view of AI model usage through a compound component system. It displays context window utilization, token consumption breakdown (input, output, reasoning, cache), and cost estimation in an interactive hover card interface.
+
+See `scripts/context.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add context
+```
+
+## Features
+
+- **Compound Component Architecture**: Flexible composition of context display elements
+- **Visual Progress Indicator**: Circular SVG progress ring showing context usage percentage
+- **Token Breakdown**: Detailed view of input, output, reasoning, and cached tokens
+- **Cost Estimation**: Real-time cost calculation using the `tokenlens` library
+- **Intelligent Formatting**: Automatic token count formatting (K, M, B suffixes)
+- **Interactive Hover Card**: Detailed information revealed on hover
+- **Context Provider Pattern**: Clean data flow through React Context API
+- **TypeScript Support**: Full type definitions for all components
+- **Accessible Design**: Proper ARIA labels and semantic HTML
+- **Theme Integration**: Uses currentColor for automatic theme adaptation
+
+## Props
+
+### `<Context />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `maxTokens` | `number` | - | The total context window size in tokens. |
+| `usedTokens` | `number` | - | The number of tokens currently used. |
+| `usage` | `LanguageModelUsage` | - | Detailed token usage breakdown from the AI SDK (input, output, reasoning, cached tokens). |
+| `modelId` | `ModelId` | - | Model identifier for cost calculation (e.g.,  |
+| `...props` | `ComponentProps<HoverCard>` | - | Any other props are spread to the HoverCard component. |
+
+### `<ContextTrigger />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom trigger element. If not provided, renders a default button with percentage and icon. |
+| `...props` | `ComponentProps<Button>` | - | Props spread to the default button element. |
+
+### `<ContextContent />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes for the hover card content. |
+| `...props` | `ComponentProps<HoverCardContent>` | - | Props spread to the HoverCardContent component. |
+
+### `<ContextContentHeader />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom header content. If not provided, renders percentage and token count with progress bar. |
+| `...props` | `ComponentProps<div>` | - | Props spread to the header div element. |
+
+### `<ContextContentBody />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Body content, typically containing usage breakdown components. |
+| `...props` | `ComponentProps<div>` | - | Props spread to the body div element. |
+
+### `<ContextContentFooter />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom footer content. If not provided, renders total cost when modelId is provided. |
+| `...props` | `ComponentProps<div>` | - | Props spread to the footer div element. |
+
+### Usage Components
+
+All usage components (`ContextInputUsage`, `ContextOutputUsage`, `ContextReasoningUsage`, `ContextCacheUsage`) share the same props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom content. If not provided, renders token count and cost for the respective usage type. |
+| `className` | `string` | - | Additional CSS classes. |
+| `...props` | `ComponentProps<div>` | - | Props spread to the div element. |
+
+## Component Architecture
+
+The Context component uses a compound component pattern with React Context for data sharing:
+
+1. **`<Context>`** - Root provider component that holds all context data
+2. **`<ContextTrigger>`** - Interactive trigger element (default: button with percentage)
+3. **`<ContextContent>`** - Hover card content container
+4. **`<ContextContentHeader>`** - Header section with progress visualization
+5. **`<ContextContentBody>`** - Body section for usage breakdowns
+6. **`<ContextContentFooter>`** - Footer section for total cost
+7. **Usage Components** - Individual token usage displays (Input, Output, Reasoning, Cache)
+
+## Token Formatting
+
+The component uses `Intl.NumberFormat` with compact notation for automatic formatting:
+
+- Under 1,000: Shows exact count (e.g., "842")
+- 1,000+: Shows with K suffix (e.g., "32K")
+- 1,000,000+: Shows with M suffix (e.g., "1.5M")
+- 1,000,000,000+: Shows with B suffix (e.g., "2.1B")
+
+## Cost Calculation
+
+When a `modelId` is provided, the component automatically calculates costs using the `tokenlens` library:
+
+- **Input tokens**: Cost based on model's input pricing
+- **Output tokens**: Cost based on model's output pricing
+- **Reasoning tokens**: Special pricing for reasoning-capable models
+- **Cached tokens**: Reduced pricing for cached input tokens
+- **Total cost**: Sum of all token type costs
+
+Costs are formatted using `Intl.NumberFormat` with USD currency.
+
+## Styling
+
+The component uses Tailwind CSS classes and follows your design system:
+
+- Progress indicator uses `currentColor` for theme adaptation
+- Hover card has customizable width and padding
+- Footer has a secondary background for visual separation
+- All text sizes use the `text-xs` class for consistency
+- Muted foreground colors for secondary information

package/.agents/skills/ai-elements/references/controls.md

@@ -0,0 +1,32 @@
+# Controls
+
+A styled controls component for React Flow-based canvases with zoom and fit view functionality.
+
+The `Controls` component provides interactive zoom and fit view controls for React Flow canvases. It includes a modern, themed design with backdrop blur and card styling.
+
+
+
+## Installation
+
+```bash
+npx ai-elements@latest add controls
+```
+
+## Features
+
+- Zoom in/out controls
+- Fit view button to center and scale content
+- Rounded pill design with backdrop blur
+- Theme-aware card background
+- Subtle drop shadow for depth
+- Full TypeScript support
+- Compatible with all React Flow control features
+
+## Props
+
+### `<Controls />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes to apply to the controls. |
+| `...props` | `ComponentProps<typeof Controls>` | - | Any other props from @xyflow/react Controls component (showZoom, showFitView, showInteractive, position, etc.). |

package/.agents/skills/ai-elements/references/conversation.md

@@ -0,0 +1,224 @@
+# Conversation
+
+Wraps messages and automatically scrolls to the bottom. Also includes a scroll button that appears when not at the bottom.
+
+The `Conversation` component wraps messages and automatically scrolls to the bottom. Also includes a scroll button that appears when not at the bottom.
+
+<Preview path="conversation" className="p-0" />
+
+## Installation
+
+```bash
+npx ai-elements@latest add conversation
+```
+
+## Usage with AI SDK
+
+Build a simple conversational UI with `Conversation` and [`PromptInput`](/components/prompt-input):
+
+Add the following component to your frontend:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import {
+  Conversation,
+  ConversationContent,
+  ConversationDownload,
+  ConversationEmptyState,
+  ConversationScrollButton,
+} from "@/components/ai-elements/conversation";
+import {
+  Message,
+  MessageContent,
+  MessageResponse,
+} from "@/components/ai-elements/message";
+import {
+  PromptInput,
+  type PromptInputMessage,
+  PromptInputTextarea,
+  PromptInputSubmit,
+} from "@/components/ai-elements/prompt-input";
+import { MessageSquare } from "lucide-react";
+import { useState } from "react";
+import { useChat } from "@ai-sdk/react";
+
+const ConversationDemo = () => {
+  const [input, setInput] = useState("");
+  const { messages, sendMessage, status } = useChat();
+
+  const handleSubmit = (message: PromptInputMessage) => {
+    if (message.text.trim()) {
+      sendMessage({ text: message.text });
+      setInput("");
+    }
+  };
+
+  return (
+    <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]">
+      <div className="flex flex-col h-full">
+        <Conversation>
+          <ConversationContent>
+            {messages.length === 0 ? (
+              <ConversationEmptyState
+                icon={<MessageSquare className="size-12" />}
+                title="Start a conversation"
+                description="Type a message below to begin chatting"
+              />
+            ) : (
+              messages.map((message) => (
+                <Message from={message.role} key={message.id}>
+                  <MessageContent>
+                    {message.parts.map((part, i) => {
+                      switch (part.type) {
+                        case "text": // we don't use any reasoning or tool calls in this example
+                          return (
+                            <MessageResponse key={`${message.id}-${i}`}>
+                              {part.text}
+                            </MessageResponse>
+                          );
+                        default:
+                          return null;
+                      }
+                    })}
+                  </MessageContent>
+                </Message>
+              ))
+            )}
+          </ConversationContent>
+          <ConversationDownload messages={messages} />
+          <ConversationScrollButton />
+        </Conversation>
+
+        <PromptInput
+          onSubmit={handleSubmit}
+          className="mt-4 w-full max-w-2xl mx-auto relative"
+        >
+          <PromptInputTextarea
+            value={input}
+            placeholder="Say something..."
+            onChange={(e) => setInput(e.currentTarget.value)}
+            className="pr-12"
+          />
+          <PromptInputSubmit
+            status={status === "streaming" ? "streaming" : "ready"}
+            disabled={!input.trim()}
+            className="absolute bottom-1 right-1"
+          />
+        </PromptInput>
+      </div>
+    </div>
+  );
+};
+
+export default ConversationDemo;
+```
+
+Add the following route to your backend:
+
+```tsx title="api/chat/route.ts"
+import { streamText, UIMessage, convertToModelMessages } from "ai";
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: "openai/gpt-4o",
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Features
+
+- Automatic scrolling to the bottom when new messages are added
+- Smooth scrolling behavior with configurable animation
+- Scroll button that appears when not at the bottom
+- Download conversation as Markdown
+- Responsive design with customizable padding and spacing
+- Flexible content layout with consistent message spacing
+- Accessible with proper ARIA roles for screen readers
+- Customizable styling through className prop
+- Support for any number of child message components
+
+## Props
+
+### `<Conversation />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `contextRef` | `React.Ref<StickToBottomContext>` | - | Optional ref to access the StickToBottom context object. |
+| `instance` | `StickToBottomInstance` | - | Optional instance for controlling the StickToBottom component. |
+| `children` | `((context: StickToBottomContext) => ReactNode) | ReactNode` | - | Render prop or ReactNode for custom rendering with context. |
+| `...props` | `Omit<React.HTMLAttributes<HTMLDivElement>, ` | - | Any other props are spread to the root div. |
+
+### `<ConversationContent />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `((context: StickToBottomContext) => ReactNode) | ReactNode` | - | Render prop or ReactNode for custom rendering with context. |
+| `...props` | `Omit<React.HTMLAttributes<HTMLDivElement>, ` | - | Any other props are spread to the root div. |
+
+### `<ConversationEmptyState />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | - | The title text to display. |
+| `description` | `string` | - | The description text to display. |
+| `icon` | `React.ReactNode` | - | Optional icon to display above the text. |
+| `children` | `React.ReactNode` | - | Optional additional content to render below the text. |
+| `...props` | `ComponentProps<` | - | Any other props are spread to the root div. |
+
+### `<ConversationScrollButton />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `ComponentProps<typeof Button>` | - | Any other props are spread to the underlying shadcn/ui Button component. |
+
+### `<ConversationDownload />`
+
+A button that downloads the conversation as a Markdown file.
+
+```tsx
+import { ConversationDownload } from "@/components/ai-elements/conversation";
+
+<Conversation>
+  <ConversationContent>
+    {messages.map(...)}
+  </ConversationContent>
+  <ConversationDownload messages={messages} />
+  <ConversationScrollButton />
+</Conversation>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `messages` | `UIMessage[]` | Required | Array of messages to include in the download. |
+| `filename` | `string` | - | The filename for the downloaded file. |
+| `formatMessage` | `(message: UIMessage, index: number) => string` | - | Custom function to format each message in the output. |
+| `...props` | `Omit<ComponentProps<typeof Button>, ` | - | Any other props are spread to the underlying shadcn/ui Button component. |
+
+### `messagesToMarkdown`
+
+A utility function to convert messages to Markdown format. Useful for custom download implementations.
+
+```tsx
+import { messagesToMarkdown } from "@/components/ai-elements/conversation";
+
+const markdown = messagesToMarkdown(messages);
+
+// With custom formatter
+const customMarkdown = messagesToMarkdown(
+  messages,
+  (msg, i) =>
+    `[${msg.role}]: ${msg.parts
+      .filter((p) => p.type === "text")
+      .map((p) => p.text)
+      .join("")}`
+);
+```

package/.agents/skills/ai-elements/references/edge.md

@@ -0,0 +1,52 @@
+# Edge
+
+Customizable edge components for React Flow canvases with animated and temporary states.
+
+The `Edge` component provides two pre-styled edge types for React Flow canvases: `Temporary` for dashed temporary connections and `Animated` for connections with animated indicators.
+
+
+
+## Installation
+
+```bash
+npx ai-elements@latest add edge
+```
+
+## Features
+
+- Two distinct edge types: Temporary and Animated
+- Temporary edges use dashed lines with ring color
+- Animated edges include a moving circle indicator
+- Automatic handle position calculation
+- Smart offset calculation based on handle type and position
+- Uses Bezier curves for smooth, natural-looking connections
+- Fully compatible with React Flow's edge system
+- Type-safe implementation with TypeScript
+
+## Edge Types
+
+### `Edge.Temporary`
+
+A dashed edge style for temporary or preview connections. Uses a simple Bezier path with a dashed stroke pattern.
+
+### `Edge.Animated`
+
+A solid edge with an animated circle that moves along the path. The animation repeats indefinitely with a 2-second duration, providing visual feedback for active connections.
+
+## Props
+
+Both edge types accept standard React Flow `EdgeProps`:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | - | Unique identifier for the edge. |
+| `source` | `string` | - | ID of the source node. |
+| `target` | `string` | - | ID of the target node. |
+| `sourceX` | `number` | - | X coordinate of the source handle (Temporary only). |
+| `sourceY` | `number` | - | Y coordinate of the source handle (Temporary only). |
+| `targetX` | `number` | - | X coordinate of the target handle (Temporary only). |
+| `targetY` | `number` | - | Y coordinate of the target handle (Temporary only). |
+| `sourcePosition` | `Position` | - | Position of the source handle (Left, Right, Top, Bottom). |
+| `targetPosition` | `Position` | - | Position of the target handle (Left, Right, Top, Bottom). |
+| `markerEnd` | `string` | - | SVG marker ID for the edge end (Animated only). |
+| `style` | `React.CSSProperties` | - | Custom styles for the edge (Animated only). |

package/.agents/skills/ai-elements/references/environment-variables.md

@@ -0,0 +1,102 @@
+# Environment Variables
+
+Display environment variables with masking and copy functionality.
+
+The `EnvironmentVariables` component displays environment variables with value masking, visibility toggle, and copy functionality.
+
+See `scripts/environment-variables.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add environment-variables
+```
+
+## Features
+
+- Value masking by default
+- Toggle visibility switch
+- Copy individual values
+- Export format support (`export KEY="value"`)
+- Required badge indicator
+
+## Props
+
+### `<EnvironmentVariables />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showValues` | `boolean` | - | Controlled visibility state. |
+| `defaultShowValues` | `boolean` | `false` | Default visibility state. |
+| `onShowValuesChange` | `(show: boolean) => void` | - | Callback when visibility changes. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the container div. |
+
+### `<EnvironmentVariablesHeader />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the header div. |
+
+### `<EnvironmentVariablesTitle />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom title text. |
+| `...props` | `React.HTMLAttributes<HTMLHeadingElement>` | - | Spread to the h3 element. |
+
+### `<EnvironmentVariablesToggle />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<typeof Switch>` | - | Spread to the Switch component. |
+
+### `<EnvironmentVariablesContent />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the content div. |
+
+### `<EnvironmentVariable />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | Required | Variable name. |
+| `value` | `string` | Required | Variable value. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the row div. |
+
+### `<EnvironmentVariableGroup />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the group div. |
+
+### `<EnvironmentVariableName />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom name content. Defaults to the name from context. |
+| `...props` | `React.HTMLAttributes<HTMLSpanElement>` | - | Spread to the span element. |
+
+### `<EnvironmentVariableValue />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom value content. Defaults to the masked/unmasked value from context. |
+| `...props` | `React.HTMLAttributes<HTMLSpanElement>` | - | Spread to the span element. |
+
+### `<EnvironmentVariableCopyButton />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `copyFormat` | `unknown` | - | Format to copy. |
+| `onCopy` | `() => void` | - | Callback after successful copy. |
+| `onError` | `(error: Error) => void` | - | Callback if copying fails. |
+| `timeout` | `number` | `2000` | Duration to show copied state (ms). |
+| `...props` | `React.ComponentProps<typeof Button>` | - | Spread to the Button component. |
+
+### `<EnvironmentVariableRequired />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom badge text. |
+| `...props` | `React.ComponentProps<typeof Badge>` | - | Spread to the Badge component. |

package/.agents/skills/ai-elements/references/file-tree.md

@@ -0,0 +1,72 @@
+# File Tree
+
+Display hierarchical file and folder structure with expand/collapse functionality.
+
+The `FileTree` component displays a hierarchical file system structure with expandable folders and file selection.
+
+See `scripts/file-tree.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add file-tree
+```
+
+## Features
+
+- Hierarchical folder structure
+- Expand/collapse folders
+- File selection with callback
+- Keyboard accessible
+- Customizable icons
+- Controlled and uncontrolled modes
+
+## Examples
+
+### Basic Usage
+
+See `scripts/file-tree-basic.tsx` for this example.
+
+### With Selection
+
+See `scripts/file-tree-selection.tsx` for this example.
+
+### Default Expanded
+
+See `scripts/file-tree-expanded.tsx` for this example.
+
+## Props
+
+### `<FileTree />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `expanded` | `Set<string>` | - | Controlled expanded paths. |
+| `defaultExpanded` | `Set<string>` | `new Set()` | Default expanded paths. |
+| `selectedPath` | `string` | - | Currently selected file/folder path. |
+| `onSelect` | `(path: string) => void` | - | Callback when a file/folder is selected. |
+| `onExpandedChange` | `(expanded: Set<string>) => void` | - | Callback when expanded paths change. |
+| `className` | `string` | - | Additional CSS classes. |
+
+### `<FileTreeFolder />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `path` | `string` | - | Unique folder path. |
+| `name` | `string` | - | Display name. |
+| `className` | `string` | - | Additional CSS classes. |
+
+### `<FileTreeFile />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `path` | `string` | - | Unique file path. |
+| `name` | `string` | - | Display name. |
+| `icon` | `ReactNode` | - | Custom file icon. |
+| `className` | `string` | - | Additional CSS classes. |
+
+### Subcomponents
+
+- `FileTreeIcon` - Icon wrapper
+- `FileTreeName` - Name text
+- `FileTreeActions` - Action buttons container (stops click propagation)