@cascivo/ai 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) cascivo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+<!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
+
+<div align="center">
+  <a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="72" height="72" alt="cascivo logo"></a>
+  <h1>@cascivo/ai</h1>
+  <p><strong>AI-native components for cascivo — StreamingText, AiLabel, Terminal, AiChat</strong></p>
+
+[![npm](https://img.shields.io/npm/v/%40cascivo%2Fai?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/ai)
+[![downloads](https://img.shields.io/npm/dm/%40cascivo%2Fai?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/ai)
+[![license](https://img.shields.io/npm/l/%40cascivo%2Fai?style=flat-square&color=0079bf)](https://github.com/cascivo/cascivo/blob/main/LICENSE)
+![types](https://img.shields.io/badge/types-included-0079bf?style=flat-square&logo=typescript&logoColor=white)
+
+[npm](https://www.npmjs.com/package/@cascivo/ai) · [cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo)
+
+</div>
+
+---
+
+AI-native components for cascivo — the presentation layer for AI features: streaming text, generation status, animated terminals, and a full chat surface. Signal-driven like the rest of the design system (no `useState`, no `useEffect`), typed, and localized via `@cascivo/i18n` built-in catalogs.
+
+> Newly published — first release on npm as of `0.1.0`.
+
+**Peer dependencies:** `react >=18` and `@preact/signals-react >=2` (the components are signal-driven). Styles ship as CSS modules bundled with the components — no stylesheet import needed. Pair with `@cascivo/themes` for tokens.
+
+```sh
+pnpm add @cascivo/ai @preact/signals-react
+```
+
+## `StreamingText`
+
+Types text out character-by-character with a blinking cursor, driven by `requestAnimationFrame`. Feed it a growing string (e.g. an accumulating LLM response) or a static one:
+
+```tsx
+import { StreamingText } from '@cascivo/ai'
+;<StreamingText
+  text={response} // target text; typing catches up as it grows
+  speed={2} // characters per frame (default 2)
+  onComplete={() => setDone(true)}
+/>
+```
+
+The cursor renders only while the displayed text lags the target, and the animation resets when `text` is replaced with a shorter string.
+
+## `AiLabel`
+
+A `role="status"` badge for AI-generated content with three variants — `generating` (default), `done`, `error`. Labels come from the `@cascivo/i18n` built-in catalog, so they localize automatically:
+
+```tsx
+import { AiLabel } from '@cascivo/ai'
+
+<AiLabel variant="generating" />
+<AiLabel variant="done" />
+<AiLabel variant="error" />
+```
+
+It extends `HTMLAttributes<HTMLSpanElement>`, so `className`, `title`, etc. pass through.
+
+## `Terminal`
+
+An animated terminal window (`role="log"`, `aria-live="polite"`) that types out a script of lines. Each line has a `type` (`command` | `output` | `error` | `comment`) for per-line styling and an optional `prefix` (e.g. `$`):
+
+```tsx
+import { Terminal } from '@cascivo/ai'
+;<Terminal
+  lines={[
+    { text: 'npx cascivo add button', prefix: '$', type: 'command' },
+    { text: 'Added button to src/components.', type: 'output' },
+    { text: '# done in 1.2s', type: 'comment' },
+  ]}
+  speed={3} // characters per frame (default 3)
+  loop // restart from the top after the last line
+  onComplete={() => {}}
+/>
+```
+
+## `AiChat`
+
+A complete chat surface: message list (`role="log"`), streaming assistant bubble, and a textarea composer with Enter-to-send (Shift+Enter for a newline). It is fully controlled — you own the message array and the send handler:
+
+```tsx
+import { AiChat, type ChatMessage } from '@cascivo/ai'
+
+const messages: ChatMessage[] = [
+  { id: '1', role: 'user', content: 'What is cascivo?' },
+  { id: '2', role: 'assistant', content: 'A CSS-native design system.' },
+]
+
+<AiChat
+  messages={messages} // system messages are accepted but not rendered
+  onSend={(text) => append({ role: 'user', content: text })}
+  isStreaming={streaming} // disables the send button
+  streamingText={partial} // rendered as a live assistant bubble via StreamingText
+/>
+```
+
+Role labels ("You" / "Assistant"), the input placeholder, and the send button label all default from the `@cascivo/i18n` built-in catalog.
+
+## Install
+
+```sh
+pnpm add @cascivo/ai
+```
+
+---
+
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/cascivo/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/cascivo/cascivo/blob/main/registry.json) · MIT
+
+<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="28" height="28" alt="cascivo"></a></div>

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+import { HTMLAttributes } from "react";
+
+//#region src/streaming-text.d.ts
+interface StreamingTextProps {
+  text: string;
+  speed?: number;
+  onComplete?: () => void;
+  className?: string;
+}
+declare function StreamingText({
+  text,
+  speed,
+  onComplete,
+  className
+}: StreamingTextProps): import("react").JSX.Element;
+//#endregion
+//#region src/ai-label.d.ts
+type AiLabelVariant = 'generating' | 'done' | 'error';
+interface AiLabelProps extends HTMLAttributes<HTMLSpanElement> {
+  variant?: AiLabelVariant;
+}
+declare function AiLabel({
+  variant,
+  className,
+  ...props
+}: AiLabelProps): import("react").JSX.Element;
+//#endregion
+//#region src/terminal.d.ts
+type TerminalLineType = 'command' | 'output' | 'error' | 'comment';
+interface TerminalLine {
+  text: string;
+  prefix?: string;
+  type?: TerminalLineType;
+}
+interface TerminalProps {
+  lines: TerminalLine[];
+  speed?: number;
+  loop?: boolean;
+  onComplete?: () => void;
+  className?: string;
+}
+declare function Terminal({
+  lines,
+  speed,
+  loop,
+  onComplete,
+  className
+}: TerminalProps): import("react").JSX.Element;
+//#endregion
+//#region src/ai-chat.d.ts
+interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+interface AiChatProps {
+  messages: ChatMessage[];
+  onSend: (text: string) => void;
+  isStreaming?: boolean;
+  streamingText?: string;
+  className?: string;
+}
+declare function AiChat({
+  messages,
+  onSend,
+  isStreaming,
+  streamingText,
+  className
+}: AiChatProps): import("react").JSX.Element;
+//#endregion
+export { AiChat, type AiChatProps, AiLabel, type AiLabelProps, type AiLabelVariant, type ChatMessage, StreamingText, type StreamingTextProps, Terminal, type TerminalLine, type TerminalLineType, type TerminalProps };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/streaming-text.tsx","../src/ai-label.tsx","../src/terminal.tsx","../src/ai-chat.tsx"],"mappings":";;;UAKiB,kBAAA;EACf,IAAA;EACA,KAAA;EACA,UAAA;EACA,SAAA;AAAA;AAAA,iBAGc,aAAA;EAAgB,IAAA;EAAM,KAAA;EAAW,UAAA;EAAY;AAAA,GAAa,kBAAA,mBAAkB,GAAA,CAAA,OAAA;;;KCNhF,cAAA;AAAA,UAEK,YAAA,SAAqB,cAAA,CAAe,eAAA;EACnD,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGI,OAAA;EAAU,OAAA;EAAwB,SAAA;EAAA,GAAc;AAAA,GAAS,YAAA,mBAAY,GAAA,CAAA,OAAA;;;KCPzE,gBAAA;AAAA,UAEK,YAAA;EACf,IAAA;EACA,MAAA;EACA,IAAA,GAAO,gBAAgB;AAAA;AAAA,UAGR,aAAA;EACf,KAAA,EAAO,YAAY;EACnB,KAAA;EACA,IAAA;EACA,UAAA;EACA,SAAA;AAAA;AAAA,iBAGc,QAAA;EAAW,KAAA;EAAO,KAAA;EAAW,IAAA;EAAc,UAAA;EAAY;AAAA,GAAa,aAAA,mBAAa,GAAA,CAAA,OAAA;;;UCdhF,WAAA;EACf,EAAA;EACA,IAAA;EACA,OAAA;AAAA;AAAA,UAGe,WAAA;EACf,QAAA,EAAU,WAAW;EACrB,MAAA,GAAS,IAAA;EACT,WAAA;EACA,aAAA;EACA,SAAA;AAAA;AAAA,iBAGc,MAAA;EACd,QAAA;EACA,MAAA;EACA,WAAA;EACA,aAAA;EACA;AAAA,GACC,WAAA,mBAAW,GAAA,CAAA,OAAA"}

package/dist/index.mjs

@@ -0,0 +1,222 @@
+import { useRef } from "react";
+import { useSignal, useSignalEffect, useSignals } from "@cascivo/core";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { builtin, t } from "@cascivo/i18n";
+//#region src/streaming-text.module.css
+var streaming_text_module_default = {
+	"cascade-cursor-blink": "dgjyMq_cascade-cursor-blink",
+	"cursor": "dgjyMq_cursor",
+	"root": "dgjyMq_root"
+};
+//#endregion
+//#region src/streaming-text.tsx
+function StreamingText({ text, speed = 2, onComplete, className }) {
+	useSignals();
+	const displayed = useSignal("");
+	const onCompleteRef = useRef(onComplete);
+	onCompleteRef.current = onComplete;
+	displayed.value = displayed.value.length > text.length ? "" : displayed.value;
+	useSignalEffect(() => {
+		const target = text;
+		if (displayed.value === target) {
+			onCompleteRef.current?.();
+			return;
+		}
+		let rafId;
+		function tick() {
+			const current = displayed.value;
+			if (current.length >= target.length) {
+				onCompleteRef.current?.();
+				return;
+			}
+			displayed.value = target.slice(0, current.length + speed);
+			rafId = requestAnimationFrame(tick);
+		}
+		rafId = requestAnimationFrame(tick);
+		return () => cancelAnimationFrame(rafId);
+	});
+	return /* @__PURE__ */ jsxs("span", {
+		className: [streaming_text_module_default.root, className].filter(Boolean).join(" "),
+		children: [displayed.value, displayed.value !== text && /* @__PURE__ */ jsx("span", {
+			className: streaming_text_module_default.cursor,
+			"aria-hidden": "true"
+		})]
+	});
+}
+//#endregion
+//#region src/ai-label.module.css
+var ai_label_module_default = {
+	"cascade-ai-pulse": "iirJiG_cascade-ai-pulse",
+	"root": "iirJiG_root"
+};
+//#endregion
+//#region src/ai-label.tsx
+function AiLabel({ variant = "generating", className, ...props }) {
+	useSignals();
+	const label = variant === "generating" ? t(builtin.ai.generating) : variant === "done" ? t(builtin.ai.done) : t(builtin.ai.error);
+	return /* @__PURE__ */ jsx("span", {
+		role: "status",
+		"aria-label": label,
+		"data-variant": variant,
+		className: [ai_label_module_default.root, className].filter(Boolean).join(" "),
+		...props,
+		children: label
+	});
+}
+//#endregion
+//#region src/terminal.module.css
+var terminal_module_default = {
+	"cascade-cursor-blink": "GFOf3W_cascade-cursor-blink",
+	"cursor": "GFOf3W_cursor",
+	"line": "GFOf3W_line",
+	"prefix": "GFOf3W_prefix",
+	"root": "GFOf3W_root",
+	"text": "GFOf3W_text"
+};
+//#endregion
+//#region src/terminal.tsx
+function Terminal({ lines, speed = 3, loop = false, onComplete, className }) {
+	useSignals();
+	const lineIndex = useSignal(0);
+	const charIndex = useSignal(0);
+	const onCompleteRef = useRef(onComplete);
+	onCompleteRef.current = onComplete;
+	useSignalEffect(() => {
+		if (lines.length === 0) return;
+		let rafId;
+		function tick() {
+			const li = lineIndex.value;
+			const ci = charIndex.value;
+			if (li >= lines.length) {
+				onCompleteRef.current?.();
+				if (loop) {
+					lineIndex.value = 0;
+					charIndex.value = 0;
+				}
+				return;
+			}
+			if (ci < lines[li].text.length) charIndex.value = ci + speed;
+			else {
+				lineIndex.value = li + 1;
+				charIndex.value = 0;
+			}
+			rafId = requestAnimationFrame(tick);
+		}
+		rafId = requestAnimationFrame(tick);
+		return () => cancelAnimationFrame(rafId);
+	});
+	const renderedLines = lines.slice(0, lineIndex.value + 1).map((line, i) => {
+		const isCurrentLine = i === lineIndex.value;
+		const text = isCurrentLine ? line.text.slice(0, charIndex.value) : line.text;
+		return /* @__PURE__ */ jsxs("div", {
+			className: terminal_module_default.line,
+			"data-type": line.type ?? "output",
+			children: [
+				line.prefix && /* @__PURE__ */ jsx("span", {
+					className: terminal_module_default.prefix,
+					children: line.prefix
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: terminal_module_default.text,
+					children: text
+				}),
+				isCurrentLine && lineIndex.value < lines.length && /* @__PURE__ */ jsx("span", {
+					className: terminal_module_default.cursor,
+					"aria-hidden": "true"
+				})
+			]
+		}, i);
+	});
+	return /* @__PURE__ */ jsx("div", {
+		role: "log",
+		"aria-live": "polite",
+		"aria-label": "Terminal output",
+		className: [terminal_module_default.root, className].filter(Boolean).join(" "),
+		children: renderedLines
+	});
+}
+//#endregion
+//#region src/ai-chat.module.css
+var ai_chat_module_default = {
+	"content": "oL95jG_content",
+	"inputArea": "oL95jG_inputArea",
+	"message": "oL95jG_message",
+	"messages": "oL95jG_messages",
+	"roleLabel": "oL95jG_roleLabel",
+	"root": "oL95jG_root",
+	"sendButton": "oL95jG_sendButton",
+	"textarea": "oL95jG_textarea"
+};
+//#endregion
+//#region src/ai-chat.tsx
+function AiChat({ messages, onSend, isStreaming = false, streamingText, className }) {
+	useSignals();
+	const inputValue = useSignal("");
+	const listRef = useRef(null);
+	function handleSend() {
+		const text = inputValue.value.trim();
+		if (!text) return;
+		onSend(text);
+		inputValue.value = "";
+	}
+	function handleKeyDown(e) {
+		if (e.key === "Enter" && !e.shiftKey) {
+			e.preventDefault();
+			handleSend();
+		}
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		className: [ai_chat_module_default.root, className].filter(Boolean).join(" "),
+		children: [/* @__PURE__ */ jsxs("div", {
+			ref: listRef,
+			className: ai_chat_module_default.messages,
+			role: "log",
+			"aria-live": "polite",
+			children: [messages.filter((m) => m.role !== "system").map((msg) => /* @__PURE__ */ jsxs("div", {
+				className: ai_chat_module_default.message,
+				"data-role": msg.role,
+				children: [/* @__PURE__ */ jsx("span", {
+					className: ai_chat_module_default.roleLabel,
+					children: msg.role === "user" ? t(builtin.ai.you) : t(builtin.ai.assistant)
+				}), /* @__PURE__ */ jsx("div", {
+					className: ai_chat_module_default.content,
+					children: msg.content
+				})]
+			}, msg.id)), isStreaming && streamingText !== void 0 && /* @__PURE__ */ jsxs("div", {
+				className: ai_chat_module_default.message,
+				"data-role": "assistant",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: ai_chat_module_default.roleLabel,
+					children: t(builtin.ai.assistant)
+				}), /* @__PURE__ */ jsx("div", {
+					className: ai_chat_module_default.content,
+					children: /* @__PURE__ */ jsx(StreamingText, { text: streamingText })
+				})]
+			})]
+		}), /* @__PURE__ */ jsxs("div", {
+			className: ai_chat_module_default.inputArea,
+			children: [/* @__PURE__ */ jsx("textarea", {
+				className: ai_chat_module_default.textarea,
+				placeholder: t(builtin.ai.placeholder),
+				value: inputValue.value,
+				onChange: (e) => {
+					inputValue.value = e.target.value;
+				},
+				onKeyDown: handleKeyDown,
+				rows: 1,
+				"aria-label": t(builtin.ai.placeholder)
+			}), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: ai_chat_module_default.sendButton,
+				onClick: handleSend,
+				disabled: isStreaming,
+				"aria-label": t(builtin.ai.send),
+				children: t(builtin.ai.send)
+			})]
+		})]
+	});
+}
+//#endregion
+export { AiChat, AiLabel, StreamingText, Terminal };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["styles","styles","styles","styles"],"sources":["../src/streaming-text.tsx","../src/ai-label.tsx","../src/terminal.tsx","../src/ai-chat.tsx"],"sourcesContent":["'use client'\nimport { useRef } from 'react'\nimport { useSignal, useSignalEffect, useSignals } from '@cascivo/core'\nimport styles from './streaming-text.module.css'\n\nexport interface StreamingTextProps {\n  text: string\n  speed?: number\n  onComplete?: () => void\n  className?: string\n}\n\nexport function StreamingText({ text, speed = 2, onComplete, className }: StreamingTextProps) {\n  useSignals()\n  const displayed = useSignal('')\n  const onCompleteRef = useRef(onComplete)\n  onCompleteRef.current = onComplete\n\n  // Reset when text prop changes\n  displayed.value = displayed.value.length > text.length ? '' : displayed.value\n\n  useSignalEffect(() => {\n    const target = text\n    if (displayed.value === target) {\n      onCompleteRef.current?.()\n      return\n    }\n    let rafId: number\n    function tick() {\n      const current = displayed.value\n      if (current.length >= target.length) {\n        onCompleteRef.current?.()\n        return\n      }\n      displayed.value = target.slice(0, current.length + speed)\n      rafId = requestAnimationFrame(tick)\n    }\n    rafId = requestAnimationFrame(tick)\n    return () => cancelAnimationFrame(rafId)\n  })\n\n  return (\n    <span className={[styles.root, className].filter(Boolean).join(' ')}>\n      {displayed.value}\n      {displayed.value !== text && <span className={styles.cursor} aria-hidden=\"true\" />}\n    </span>\n  )\n}\n","'use client'\nimport { useSignals } from '@cascivo/core'\nimport { builtin, t } from '@cascivo/i18n'\nimport styles from './ai-label.module.css'\nimport type { HTMLAttributes } from 'react'\n\nexport type AiLabelVariant = 'generating' | 'done' | 'error'\n\nexport interface AiLabelProps extends HTMLAttributes<HTMLSpanElement> {\n  variant?: AiLabelVariant\n}\n\nexport function AiLabel({ variant = 'generating', className, ...props }: AiLabelProps) {\n  useSignals()\n  const label =\n    variant === 'generating'\n      ? t(builtin.ai.generating)\n      : variant === 'done'\n        ? t(builtin.ai.done)\n        : t(builtin.ai.error)\n\n  return (\n    <span\n      role=\"status\"\n      aria-label={label}\n      data-variant={variant}\n      className={[styles.root, className].filter(Boolean).join(' ')}\n      {...props}\n    >\n      {label}\n    </span>\n  )\n}\n","'use client'\nimport { useRef } from 'react'\nimport { useSignal, useSignalEffect, useSignals } from '@cascivo/core'\nimport styles from './terminal.module.css'\n\nexport type TerminalLineType = 'command' | 'output' | 'error' | 'comment'\n\nexport interface TerminalLine {\n  text: string\n  prefix?: string\n  type?: TerminalLineType\n}\n\nexport interface TerminalProps {\n  lines: TerminalLine[]\n  speed?: number\n  loop?: boolean\n  onComplete?: () => void\n  className?: string\n}\n\nexport function Terminal({ lines, speed = 3, loop = false, onComplete, className }: TerminalProps) {\n  useSignals()\n  const lineIndex = useSignal(0)\n  const charIndex = useSignal(0)\n  const onCompleteRef = useRef(onComplete)\n  onCompleteRef.current = onComplete\n\n  useSignalEffect(() => {\n    if (lines.length === 0) return\n    let rafId: number\n    function tick() {\n      const li = lineIndex.value\n      const ci = charIndex.value\n      if (li >= lines.length) {\n        onCompleteRef.current?.()\n        if (loop) {\n          lineIndex.value = 0\n          charIndex.value = 0\n        }\n        return\n      }\n      const line = lines[li]!\n      const target = line.text\n      if (ci < target.length) {\n        charIndex.value = ci + speed\n      } else {\n        lineIndex.value = li + 1\n        charIndex.value = 0\n      }\n      rafId = requestAnimationFrame(tick)\n    }\n    rafId = requestAnimationFrame(tick)\n    return () => cancelAnimationFrame(rafId)\n  })\n\n  const renderedLines = lines.slice(0, lineIndex.value + 1).map((line, i) => {\n    const isCurrentLine = i === lineIndex.value\n    const text = isCurrentLine ? line.text.slice(0, charIndex.value) : line.text\n    return (\n      <div key={i} className={styles.line} data-type={line.type ?? 'output'}>\n        {line.prefix && <span className={styles.prefix}>{line.prefix}</span>}\n        <span className={styles.text}>{text}</span>\n        {isCurrentLine && lineIndex.value < lines.length && (\n          <span className={styles.cursor} aria-hidden=\"true\" />\n        )}\n      </div>\n    )\n  })\n\n  return (\n    <div\n      role=\"log\"\n      aria-live=\"polite\"\n      aria-label=\"Terminal output\"\n      className={[styles.root, className].filter(Boolean).join(' ')}\n    >\n      {renderedLines}\n    </div>\n  )\n}\n","'use client'\nimport { useRef } from 'react'\nimport { useSignal, useSignals } from '@cascivo/core'\nimport { builtin, t } from '@cascivo/i18n'\nimport { StreamingText } from './streaming-text'\nimport styles from './ai-chat.module.css'\n\nexport interface ChatMessage {\n  id: string\n  role: 'user' | 'assistant' | 'system'\n  content: string\n}\n\nexport interface AiChatProps {\n  messages: ChatMessage[]\n  onSend: (text: string) => void\n  isStreaming?: boolean\n  streamingText?: string\n  className?: string\n}\n\nexport function AiChat({\n  messages,\n  onSend,\n  isStreaming = false,\n  streamingText,\n  className,\n}: AiChatProps) {\n  useSignals()\n  const inputValue = useSignal('')\n  const listRef = useRef<HTMLDivElement>(null)\n\n  function handleSend() {\n    const text = inputValue.value.trim()\n    if (!text) return\n    onSend(text)\n    inputValue.value = ''\n  }\n\n  function handleKeyDown(e: React.KeyboardEvent<HTMLTextAreaElement>) {\n    if (e.key === 'Enter' && !e.shiftKey) {\n      e.preventDefault()\n      handleSend()\n    }\n  }\n\n  return (\n    <div className={[styles.root, className].filter(Boolean).join(' ')}>\n      <div ref={listRef} className={styles.messages} role=\"log\" aria-live=\"polite\">\n        {messages\n          .filter((m) => m.role !== 'system')\n          .map((msg) => (\n            <div key={msg.id} className={styles.message} data-role={msg.role}>\n              <span className={styles.roleLabel}>\n                {msg.role === 'user' ? t(builtin.ai.you) : t(builtin.ai.assistant)}\n              </span>\n              <div className={styles.content}>{msg.content}</div>\n            </div>\n          ))}\n        {isStreaming && streamingText !== undefined && (\n          <div className={styles.message} data-role=\"assistant\">\n            <span className={styles.roleLabel}>{t(builtin.ai.assistant)}</span>\n            <div className={styles.content}>\n              <StreamingText text={streamingText} />\n            </div>\n          </div>\n        )}\n      </div>\n      <div className={styles.inputArea}>\n        <textarea\n          className={styles.textarea}\n          placeholder={t(builtin.ai.placeholder)}\n          value={inputValue.value}\n          onChange={(e) => {\n            inputValue.value = e.target.value\n          }}\n          onKeyDown={handleKeyDown}\n          rows={1}\n          aria-label={t(builtin.ai.placeholder)}\n        />\n        <button\n          type=\"button\"\n          className={styles.sendButton}\n          onClick={handleSend}\n          disabled={isStreaming}\n          aria-label={t(builtin.ai.send)}\n        >\n          {t(builtin.ai.send)}\n        </button>\n      </div>\n    </div>\n  )\n}\n"],"mappings":"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"}

package/dist/style.css

@@ -0,0 +1,217 @@
+@layer cascivo.component {
+  .dgjyMq_root {
+    display: inline;
+  }
+
+  .dgjyMq_cursor {
+    vertical-align: text-bottom;
+    background: currentColor;
+    width: 2px;
+    height: 1em;
+    margin-inline-start: 1px;
+    animation: 1s step-end infinite dgjyMq_cascade-cursor-blink;
+    display: inline-block;
+  }
+}
+
+@keyframes dgjyMq_cascade-cursor-blink {
+  0%, 100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0;
+  }
+}
+@layer cascivo.component {
+  .iirJiG_root {
+    align-items: center;
+    gap: var(--cascivo-space-1);
+    padding: var(--cascivo-space-1) var(--cascivo-space-2);
+    border-radius: var(--cascivo-radius-indicator);
+    font-size: var(--cascivo-font-size-xs);
+    font-weight: 500;
+    line-height: 1;
+    display: inline-flex;
+  }
+
+  .iirJiG_root[data-variant="generating"] {
+    background: var(--cascivo-color-surface-2);
+    color: var(--cascivo-color-foreground-muted);
+  }
+
+  .iirJiG_root[data-variant="generating"]:before {
+    content: "";
+    border-radius: var(--cascivo-radius-full);
+    background: currentColor;
+    block-size: .375rem;
+    inline-size: .375rem;
+    animation: 1.5s ease-in-out infinite iirJiG_cascade-ai-pulse;
+  }
+
+  .iirJiG_root[data-variant="done"] {
+    background: var(--cascivo-color-success-subtle);
+    color: var(--cascivo-color-success-foreground);
+  }
+
+  .iirJiG_root[data-variant="error"] {
+    background: var(--cascivo-color-destructive-subtle);
+    color: var(--cascivo-color-destructive-foreground);
+  }
+}
+
+@keyframes iirJiG_cascade-ai-pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: .6;
+  }
+}
+@layer cascivo.component {
+  .GFOf3W_root {
+    color: oklch(90% .02 145);
+    font-family: ui-monospace, Cascadia Code, Source Code Pro, monospace;
+    font-size: var(--cascivo-font-size-sm, .875rem);
+    padding: var(--cascivo-space-4);
+    border-radius: var(--cascivo-radius-surface);
+    background: oklch(12% .01 250);
+    line-height: 1.6;
+    overflow-x: auto;
+  }
+
+  .GFOf3W_line {
+    gap: var(--cascivo-space-2);
+    display: flex;
+  }
+
+  .GFOf3W_prefix {
+    color: oklch(70% .15 145);
+    user-select: none;
+  }
+
+  .GFOf3W_text {
+    flex: 1;
+  }
+
+  .GFOf3W_cursor {
+    background: oklch(90% .02 145);
+    width: 8px;
+    height: 1em;
+    animation: 1s step-end infinite GFOf3W_cascade-cursor-blink;
+    display: inline-block;
+  }
+
+  .GFOf3W_line[data-type="command"] .GFOf3W_text {
+    color: oklch(90% .1 250);
+  }
+
+  .GFOf3W_line[data-type="error"] .GFOf3W_text {
+    color: oklch(75% .15 22);
+  }
+
+  .GFOf3W_line[data-type="comment"] .GFOf3W_text {
+    color: oklch(60% .02 145);
+  }
+}
+
+@keyframes GFOf3W_cascade-cursor-blink {
+  0%, 100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0;
+  }
+}
+@layer cascivo.component {
+  .oL95jG_root {
+    background: var(--cascivo-color-background);
+    border: 1px solid var(--cascivo-border-default);
+    border-radius: var(--cascivo-radius-surface);
+    flex-direction: column;
+    height: 100%;
+    min-height: 400px;
+    display: flex;
+    overflow: hidden;
+  }
+
+  .oL95jG_messages {
+    padding: var(--cascivo-space-4);
+    gap: var(--cascivo-space-3);
+    flex-direction: column;
+    flex: 1;
+    display: flex;
+    overflow-y: auto;
+  }
+
+  .oL95jG_message {
+    gap: var(--cascivo-space-1);
+    flex-direction: column;
+    max-width: 80%;
+    display: flex;
+  }
+
+  .oL95jG_message[data-role="user"] {
+    align-self: flex-end;
+    align-items: flex-end;
+  }
+
+  .oL95jG_message[data-role="assistant"] {
+    align-self: flex-start;
+  }
+
+  .oL95jG_roleLabel {
+    font-size: var(--cascivo-font-size-xs, .75rem);
+    color: var(--cascivo-color-foreground-muted);
+    font-weight: 500;
+  }
+
+  .oL95jG_content {
+    padding: var(--cascivo-space-2) var(--cascivo-space-3);
+    border-radius: var(--cascivo-radius-control);
+    background: var(--cascivo-color-surface);
+    line-height: 1.5;
+  }
+
+  .oL95jG_message[data-role="user"] .oL95jG_content {
+    background: var(--cascivo-color-accent);
+    color: var(--cascivo-color-accent-foreground);
+  }
+
+  .oL95jG_inputArea {
+    gap: var(--cascivo-space-2);
+    padding: var(--cascivo-space-3);
+    border-block-start: 1px solid var(--cascivo-border-subtle);
+    background: var(--cascivo-color-surface);
+    display: flex;
+  }
+
+  .oL95jG_textarea {
+    resize: none;
+    border: 1px solid var(--cascivo-border-default);
+    border-radius: var(--cascivo-radius-control);
+    padding: var(--cascivo-space-2) var(--cascivo-space-3);
+    font: inherit;
+    background: var(--cascivo-color-background);
+    color: var(--cascivo-color-foreground);
+    flex: 1;
+  }
+
+  .oL95jG_sendButton {
+    padding: var(--cascivo-space-2) var(--cascivo-space-4);
+    background: var(--cascivo-color-accent);
+    color: var(--cascivo-color-accent-foreground);
+    border-radius: var(--cascivo-radius-control);
+    font: inherit;
+    cursor: pointer;
+    border: none;
+    font-weight: 500;
+  }
+
+  .oL95jG_sendButton:disabled {
+    opacity: .5;
+    cursor: not-allowed;
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@cascivo/ai",
+  "version": "0.2.3",
+  "description": "AI-native components for cascivo — StreamingText, AiLabel, Terminal, AiChat",
+  "keywords": [
+    "ai",
+    "cascivo",
+    "chat",
+    "css",
+    "design-system",
+    "react",
+    "signals",
+    "streaming"
+  ],
+  "homepage": "https://github.com/cascivo/cascivo/tree/main/packages/ai#readme",
+  "license": "MIT",
+  "author": "urbanisierung",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cascivo/cascivo.git",
+    "directory": "packages/ai"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@cascivo/core": "^0.2.6",
+    "@cascivo/tokens": "^0.3.8",
+    "@cascivo/i18n": "^0.2.3"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
+    "typescript": "^5",
+    "vite-plus": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@preact/signals-react": ">=2.0.0",
+    "react": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "tsc --noEmit",
+    "test": "vp test",
+    "dev": "vp pack --watch"
+  }
+}

package/readme.body.md

@@ -0,0 +1,78 @@
+AI-native components for cascivo — the presentation layer for AI features: streaming text, generation status, animated terminals, and a full chat surface. Signal-driven like the rest of the design system (no `useState`, no `useEffect`), typed, and localized via `@cascivo/i18n` built-in catalogs.
+
+> Newly published — first release on npm as of `0.1.0`.
+
+**Peer dependencies:** `react >=18` and `@preact/signals-react >=2` (the components are signal-driven). Styles ship as CSS modules bundled with the components — no stylesheet import needed. Pair with `@cascivo/themes` for tokens.
+
+```sh
+pnpm add @cascivo/ai @preact/signals-react
+```
+
+## `StreamingText`
+
+Types text out character-by-character with a blinking cursor, driven by `requestAnimationFrame`. Feed it a growing string (e.g. an accumulating LLM response) or a static one:
+
+```tsx
+import { StreamingText } from '@cascivo/ai'
+;<StreamingText
+  text={response} // target text; typing catches up as it grows
+  speed={2} // characters per frame (default 2)
+  onComplete={() => setDone(true)}
+/>
+```
+
+The cursor renders only while the displayed text lags the target, and the animation resets when `text` is replaced with a shorter string.
+
+## `AiLabel`
+
+A `role="status"` badge for AI-generated content with three variants — `generating` (default), `done`, `error`. Labels come from the `@cascivo/i18n` built-in catalog, so they localize automatically:
+
+```tsx
+import { AiLabel } from '@cascivo/ai'
+
+<AiLabel variant="generating" />
+<AiLabel variant="done" />
+<AiLabel variant="error" />
+```
+
+It extends `HTMLAttributes<HTMLSpanElement>`, so `className`, `title`, etc. pass through.
+
+## `Terminal`
+
+An animated terminal window (`role="log"`, `aria-live="polite"`) that types out a script of lines. Each line has a `type` (`command` | `output` | `error` | `comment`) for per-line styling and an optional `prefix` (e.g. `$`):
+
+```tsx
+import { Terminal } from '@cascivo/ai'
+;<Terminal
+  lines={[
+    { text: 'npx cascivo add button', prefix: '$', type: 'command' },
+    { text: 'Added button to src/components.', type: 'output' },
+    { text: '# done in 1.2s', type: 'comment' },
+  ]}
+  speed={3} // characters per frame (default 3)
+  loop // restart from the top after the last line
+  onComplete={() => {}}
+/>
+```
+
+## `AiChat`
+
+A complete chat surface: message list (`role="log"`), streaming assistant bubble, and a textarea composer with Enter-to-send (Shift+Enter for a newline). It is fully controlled — you own the message array and the send handler:
+
+```tsx
+import { AiChat, type ChatMessage } from '@cascivo/ai'
+
+const messages: ChatMessage[] = [
+  { id: '1', role: 'user', content: 'What is cascivo?' },
+  { id: '2', role: 'assistant', content: 'A CSS-native design system.' },
+]
+
+<AiChat
+  messages={messages} // system messages are accepted but not rendered
+  onSend={(text) => append({ role: 'user', content: text })}
+  isStreaming={streaming} // disables the send button
+  streamingText={partial} // rendered as a live assistant bubble via StreamingText
+/>
+```
+
+Role labels ("You" / "Assistant"), the input placeholder, and the send button label all default from the `@cascivo/i18n` built-in catalog.