zilmate 1.7.8 → 1.8.0

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

@@ -0,0 +1,146 @@
+# Image
+
+Displays AI-generated images from the AI SDK.
+
+The `Image` component displays AI-generated images from the AI SDK. It accepts a [`Experimental_GeneratedImage`](/docs/reference/ai-sdk-core/generate-image) object from the AI SDK's `generateImage` function and automatically renders it as an image.
+
+See `scripts/image.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add image
+```
+
+## Usage with AI SDK
+
+Build a simple app allowing a user to generate an image given a prompt.
+
+Install the `@ai-sdk/openai` package:
+
+```package-install
+npm i @ai-sdk/openai
+```
+
+Add the following component to your frontend:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { Image } from "@/components/ai-elements/image";
+import {
+  PromptInput,
+  type PromptInputMessage,
+  PromptInputTextarea,
+  PromptInputSubmit,
+} from "@/components/ai-elements/prompt-input";
+import { useState } from "react";
+import { Spinner } from "@/components/ui/spinner";
+
+const ImageDemo = () => {
+  const [prompt, setPrompt] = useState("A futuristic cityscape at sunset");
+  const [imageData, setImageData] = useState<any>(null);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleSubmit = async (message: PromptInputMessage) => {
+    if (!message.text.trim()) return;
+    setPrompt("");
+
+    setIsLoading(true);
+    try {
+      const response = await fetch("/api/image", {
+        method: "POST",
+        body: JSON.stringify({ prompt: message.text.trim() }),
+      });
+
+      const data = await response.json();
+
+      setImageData(data);
+    } catch (error) {
+      console.error("Error generating image:", error);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  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">
+        <div className="flex-1 overflow-y-auto p-4">
+          {imageData && (
+            <div className="flex justify-center">
+              <Image
+                {...imageData}
+                alt="Generated image"
+                className="h-[300px] aspect-square border rounded-lg"
+              />
+            </div>
+          )}
+          {isLoading && <Spinner />}
+        </div>
+
+        <PromptInput
+          onSubmit={handleSubmit}
+          className="mt-4 w-full max-w-2xl mx-auto relative"
+        >
+          <PromptInputTextarea
+            value={prompt}
+            placeholder="Describe the image you want to generate..."
+            onChange={(e) => setPrompt(e.currentTarget.value)}
+            className="pr-12"
+          />
+          <PromptInputSubmit
+            status={isLoading ? "submitted" : "ready"}
+            disabled={!prompt.trim()}
+            className="absolute bottom-1 right-1"
+          />
+        </PromptInput>
+      </div>
+    </div>
+  );
+};
+
+export default ImageDemo;
+```
+
+Add the following route to your backend:
+
+```ts title="app/api/image/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { experimental_generateImage } from "ai";
+
+export async function POST(req: Request) {
+  const { prompt }: { prompt: string } = await req.json();
+
+  const { image } = await experimental_generateImage({
+    model: openai.image("dall-e-3"),
+    prompt: prompt,
+    size: "1024x1024",
+  });
+
+  return Response.json({
+    base64: image.base64,
+    uint8Array: image.uint8Array,
+    mediaType: image.mediaType,
+  });
+}
+```
+
+## Features
+
+- Accepts `Experimental_GeneratedImage` objects directly from the AI SDK
+- Automatically creates proper data URLs from base64-encoded image data
+- Supports all standard HTML image attributes
+- Responsive by default with `max-w-full h-auto` styling
+- Customizable with additional CSS classes
+- Includes proper TypeScript types for AI SDK compatibility
+
+## Props
+
+### `<Image />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `alt` | `string` | - | Alternative text for the image. |
+| `className` | `string` | - | Additional CSS classes to apply to the image. |
+| `...props` | `Experimental_GeneratedImage` | - | The image data to display, as returned by the AI SDK. |

package/.agents/skills/ai-elements/references/inline-citation.md

@@ -0,0 +1,299 @@
+# Inline Citation
+
+A hoverable citation component that displays source information and quotes inline with text, perfect for AI-generated content with references.
+
+The `InlineCitation` component provides a way to display citations inline with text content, similar to academic papers or research documents. It consists of a citation pill that shows detailed source information on hover, making it perfect for AI-generated content that needs to reference sources.
+
+See `scripts/inline-citation.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add inline-citation
+```
+
+## Usage with AI SDK
+
+Build citations for AI-generated content using [`experimental_generateObject`](/docs/reference/ai-sdk-ui/use-object).
+
+Add the following component to your frontend:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { experimental_useObject as useObject } from "@ai-sdk/react";
+import {
+  InlineCitation,
+  InlineCitationText,
+  InlineCitationCard,
+  InlineCitationCardTrigger,
+  InlineCitationCardBody,
+  InlineCitationCarousel,
+  InlineCitationCarouselContent,
+  InlineCitationCarouselItem,
+  InlineCitationCarouselHeader,
+  InlineCitationCarouselIndex,
+  InlineCitationCarouselPrev,
+  InlineCitationCarouselNext,
+  InlineCitationSource,
+  InlineCitationQuote,
+} from "@/components/ai-elements/inline-citation";
+import { Button } from "@/components/ui/button";
+import { citationSchema } from "@/app/api/citation/route";
+
+const CitationDemo = () => {
+  const { object, submit, isLoading } = useObject({
+    api: "/api/citation",
+    schema: citationSchema,
+  });
+
+  const handleSubmit = (topic: string) => {
+    submit({ prompt: topic });
+  };
+
+  return (
+    <div className="max-w-4xl mx-auto p-6 space-y-6">
+      <div className="flex gap-2 mb-6">
+        <Button
+          onClick={() => handleSubmit("artificial intelligence")}
+          disabled={isLoading}
+          variant="outline"
+        >
+          Generate AI Content
+        </Button>
+        <Button
+          onClick={() => handleSubmit("climate change")}
+          disabled={isLoading}
+          variant="outline"
+        >
+          Generate Climate Content
+        </Button>
+      </div>
+
+      {isLoading && !object && (
+        <div className="text-muted-foreground">
+          Generating content with citations...
+        </div>
+      )}
+
+      {object?.content && (
+        <div className="prose prose-sm max-w-none">
+          <p className="leading-relaxed">
+            {object.content.split(/(\[\d+\])/).map((part, index) => {
+              const citationMatch = part.match(/\[(\d+)\]/);
+              if (citationMatch) {
+                const citationNumber = citationMatch[1];
+                const citation = object.citations?.find(
+                  (c: any) => c.number === citationNumber
+                );
+
+                if (citation) {
+                  return (
+                    <InlineCitation key={index}>
+                      <InlineCitationCard>
+                        <InlineCitationCardTrigger sources={[citation.url]} />
+                        <InlineCitationCardBody>
+                          <InlineCitationCarousel>
+                            <InlineCitationCarouselHeader>
+                              <InlineCitationCarouselPrev />
+                              <InlineCitationCarouselNext />
+                              <InlineCitationCarouselIndex />
+                            </InlineCitationCarouselHeader>
+                            <InlineCitationCarouselContent>
+                              <InlineCitationCarouselItem>
+                                <InlineCitationSource
+                                  title={citation.title}
+                                  url={citation.url}
+                                  description={citation.description}
+                                />
+                                {citation.quote && (
+                                  <InlineCitationQuote>
+                                    {citation.quote}
+                                  </InlineCitationQuote>
+                                )}
+                              </InlineCitationCarouselItem>
+                            </InlineCitationCarouselContent>
+                          </InlineCitationCarousel>
+                        </InlineCitationCardBody>
+                      </InlineCitationCard>
+                    </InlineCitation>
+                  );
+                }
+              }
+              return part;
+            })}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default CitationDemo;
+```
+
+Add the following route to your backend:
+
+```ts title="app/api/citation/route.ts"
+import { streamObject } from "ai";
+import { z } from "zod";
+
+export const citationSchema = z.object({
+  content: z.string(),
+  citations: z.array(
+    z.object({
+      number: z.string(),
+      title: z.string(),
+      url: z.string(),
+      description: z.string().optional(),
+      quote: z.string().optional(),
+    })
+  ),
+});
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json();
+
+  const result = streamObject({
+    model: "openai/gpt-4o",
+    schema: citationSchema,
+    prompt: `Generate a well-researched paragraph about ${prompt} with proper citations.
+
+    Include:
+    - A comprehensive paragraph with inline citations marked as [1], [2], etc.
+    - 2-3 citations with realistic source information
+    - Each citation should have a title, URL, and optional description/quote
+    - Make the content informative and the sources credible
+
+    Format citations as numbered references within the text.`,
+  });
+
+  return result.toTextStreamResponse();
+}
+```
+
+## Features
+
+- Hover interaction to reveal detailed citation information
+- **Carousel navigation** for multiple citations with prev/next controls
+- **Live index tracking** showing current slide position (e.g., "1/5")
+- Support for source titles, URLs, and descriptions
+- Optional quote blocks for relevant excerpts
+- Composable architecture for flexible citation formats
+- Accessible design with proper keyboard navigation
+- Seamless integration with AI-generated content
+- Clean visual design that doesn't disrupt reading flow
+- Smart badge display showing source hostname and count
+
+## Usage with AI SDK
+
+Currently, there is no official support for inline citations with Streamdown or the Response component. This is because:
+
+- There isn't any good markdown syntax for inline citations
+- Language models don't naturally respond with inline citation syntax
+- The AI SDK doesn't have built-in support for inline citations
+
+### Potential Approaches
+
+While these methods are hypothetical and not officially supported, there are two conceptual ways inline citations could work with Streamdown:
+
+1. **Footnote conversion**: GitHub Flavored Markdown (GFM) handles footnotes using `[^1]` syntax. You could hypothetically remove the default footnote rendering and convert footnotes to inline citations instead.
+
+2. **Custom HTML syntax**: You could add a system prompt instructing the model to use a special HTML syntax like `<citation />` and pass that as a custom component to Streamdown.
+
+These approaches require custom implementation and are not currently supported out of the box. We will investigate official support for this use case in the future.
+
+For now, the recommended approach is to use `experimental_useObject` (as shown in the usage example above) to generate structured citation data, then manually parse and render inline citations.
+
+## Props
+
+### `<InlineCitation />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the root span element. |
+
+### `<InlineCitationText />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying span element. |
+
+### `<InlineCitationCard />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the HoverCard component. |
+
+### `<InlineCitationCardTrigger />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sources` | `string[]` | - | Array of source URLs. The length determines the number displayed in the badge. |
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying button element. |
+
+### `<InlineCitationCardBody />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |
+
+### `<InlineCitationCarousel />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<typeof Carousel>` | - | Any other props are spread to the underlying Carousel component. |
+
+### `<InlineCitationCarouselContent />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying CarouselContent component. |
+
+### `<InlineCitationCarouselItem />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |
+
+### `<InlineCitationCarouselHeader />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |
+
+### `<InlineCitationCarouselIndex />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. Children will override the default index display. |
+
+### `<InlineCitationCarouselPrev />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<typeof CarouselPrevious>` | - | Any other props are spread to the underlying CarouselPrevious component. |
+
+### `<InlineCitationCarouselNext />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<typeof CarouselNext>` | - | Any other props are spread to the underlying CarouselNext component. |
+
+### `<InlineCitationSource />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | - | The title of the source. |
+| `url` | `string` | - | The URL of the source. |
+| `description` | `string` | - | A brief description of the source. |
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |
+
+### `<InlineCitationQuote />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying blockquote element. |

package/.agents/skills/ai-elements/references/jsx-preview.md

@@ -0,0 +1,104 @@
+# JSX Preview
+
+A component that dynamically renders JSX strings with streaming support for AI-generated UI.
+
+The `JSXPreview` component renders JSX strings dynamically, supporting streaming scenarios where JSX may be incomplete. It automatically closes unclosed tags during streaming, making it ideal for displaying AI-generated UI components in real-time.
+
+See `scripts/jsx-preview.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add jsx-preview
+```
+
+## Features
+
+- Renders JSX strings dynamically using `react-jsx-parser`
+- Streaming support with automatic tag completion
+- Custom component injection for rendering your own components
+- Error handling with customizable error display
+- Context-based architecture for flexible composition
+
+## Usage with AI SDK
+
+The JSXPreview component integrates with the AI SDK to render generated UI in real-time:
+
+```tsx title="components/generated-ui.tsx"
+"use client";
+
+import {
+  JSXPreview,
+  JSXPreviewContent,
+  JSXPreviewError,
+} from "@/components/ai-elements/jsx-preview";
+
+type GeneratedUIProps = {
+  jsx: string;
+  isStreaming: boolean;
+};
+
+export const GeneratedUI = ({ jsx, isStreaming }: GeneratedUIProps) => (
+  <JSXPreview
+    jsx={jsx}
+    isStreaming={isStreaming}
+    onError={(error) => console.error("JSX Parse Error:", error)}
+  >
+    <JSXPreviewContent />
+    <JSXPreviewError />
+  </JSXPreview>
+);
+```
+
+### With Custom Components
+
+You can inject custom components to be used within the rendered JSX:
+
+```tsx title="components/generated-ui-with-components.tsx"
+"use client";
+
+import {
+  JSXPreview,
+  JSXPreviewContent,
+} from "@/components/ai-elements/jsx-preview";
+import { Button } from "@/components/ui/button";
+import { Card } from "@/components/ui/card";
+
+const customComponents = {
+  Button,
+  Card,
+};
+
+export const GeneratedUIWithComponents = ({ jsx }: { jsx: string }) => (
+  <JSXPreview jsx={jsx} components={customComponents}>
+    <JSXPreviewContent />
+  </JSXPreview>
+);
+```
+
+## Props
+
+### `<JSXPreview />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `jsx` | `string` | Required | The JSX string to render. |
+| `isStreaming` | `boolean` | `false` | When true, automatically completes unclosed tags. |
+| `components` | `Record<string, React.ComponentType>` | - | Custom components available within the rendered JSX. |
+| `bindings` | `Record<string, unknown>` | - | Variables and functions available within the JSX scope. |
+| `onError` | `(error: Error) => void` | - | Callback fired when a parsing or rendering error occurs. |
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div element. |
+
+### `<JSXPreviewContent />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `renderError` | `JsxParserProps[` | - | Custom error renderer passed to react-jsx-parser. |
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div element. |
+
+### `<JSXPreviewError />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode | ((error: Error) => ReactNode)` | - | Custom error content or render function receiving the error. |
+| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div element. |