@kitnai/chat 0.1.0

package/src/stories/checkpoint-restore.stories.tsx

@@ -0,0 +1,224 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import {
+  ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageAvatar, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  Checkpoint, CheckpointIcon, CheckpointTrigger,
+  Button, Separator,
+} from '../index';
+import { Copy, ThumbsUp, ThumbsDown, ArrowUp, RotateCcw } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Examples/Checkpoint & Restore',
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => {
+    const [restoredTo, setRestoredTo] = createSignal<string | null>(null);
+
+    return (
+      <div class="flex flex-col h-[700px] w-full max-w-2xl bg-background rounded-xl shadow-lg overflow-hidden">
+        <div class="flex items-center justify-between px-4 py-3">
+          <h2 class="text-sm font-semibold text-foreground">API Design Session</h2>
+          {restoredTo() && (
+            <span class="text-xs text-muted-foreground bg-muted px-2 py-1 rounded-md">
+              Restored to checkpoint: {restoredTo()}
+            </span>
+          )}
+        </div>
+        <Separator />
+
+        <ChatContainer class="flex-1 p-4">
+          <ChatContainerContent class="space-y-6 py-4">
+
+            {/* Initial exchange */}
+            <Message>
+              <MessageAvatar src="" fallback="U" alt="User" />
+              <MessageContent>
+                I'm designing a REST API for a task management app. What should the core endpoints look like?
+              </MessageContent>
+            </Message>
+
+            <Message>
+              <MessageAvatar src="" fallback="AI" alt="Assistant" />
+              <div class="flex-1 space-y-2">
+                <MessageContent markdown>
+{`Here's a clean REST resource design for task management:
+
+\`\`\`
+GET    /api/tasks              # List tasks (with filters)
+POST   /api/tasks              # Create task
+GET    /api/tasks/:id          # Get single task
+PATCH  /api/tasks/:id          # Update task
+DELETE /api/tasks/:id          # Delete task
+
+GET    /api/projects           # List projects
+POST   /api/projects           # Create project
+GET    /api/projects/:id/tasks # Tasks within a project
+\`\`\`
+
+Key design decisions:
+- Use **PATCH** over PUT for partial updates
+- Nest tasks under projects for scoped queries
+- Support filtering via query params: \`?status=active&assignee=me\``}
+                </MessageContent>
+                <MessageActions>
+                  <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
+                  <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
+                  <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
+                </MessageActions>
+              </div>
+            </Message>
+
+            {/* First checkpoint */}
+            <Checkpoint>
+              <CheckpointIcon />
+              <CheckpointTrigger
+                tooltip="Restore to this point"
+                onClick={() => setRestoredTo('API structure defined')}
+              >
+                <div class="flex items-center gap-1.5 text-xs">
+                  <RotateCcw class="size-3" />
+                  <span>API structure defined</span>
+                </div>
+              </CheckpointTrigger>
+            </Checkpoint>
+
+            {/* Second exchange */}
+            <Message>
+              <MessageAvatar src="" fallback="U" alt="User" />
+              <MessageContent>
+                What about authentication? Should I use JWT or session cookies?
+              </MessageContent>
+            </Message>
+
+            <Message>
+              <MessageAvatar src="" fallback="AI" alt="Assistant" />
+              <div class="flex-1 space-y-2">
+                <MessageContent markdown>
+{`For a task management API, I'd recommend **JWT with refresh tokens**:
+
+\`\`\`typescript
+// Auth endpoints
+POST /api/auth/login     // Returns access + refresh tokens
+POST /api/auth/refresh   // Exchanges refresh for new access token
+POST /api/auth/logout    // Invalidates refresh token
+
+// Middleware
+function authMiddleware(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1];
+  try {
+    req.user = jwt.verify(token, SECRET);
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+}
+\`\`\`
+
+**Why JWT over sessions:**
+- Stateless -- no server-side session store needed
+- Works across subdomains and mobile apps
+- Access tokens expire in 15min, limiting damage from theft
+
+**The tradeoff:** you can't instantly revoke JWTs. Mitigate this with short expiry + a blocklist for critical cases (password change, account compromise).`}
+                </MessageContent>
+                <MessageActions>
+                  <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
+                  <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
+                  <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
+                </MessageActions>
+              </div>
+            </Message>
+
+            {/* Second checkpoint */}
+            <Checkpoint>
+              <CheckpointIcon />
+              <CheckpointTrigger
+                tooltip="Restore to this point"
+                onClick={() => setRestoredTo('Auth strategy chosen')}
+              >
+                <div class="flex items-center gap-1.5 text-xs">
+                  <RotateCcw class="size-3" />
+                  <span>Auth strategy chosen</span>
+                </div>
+              </CheckpointTrigger>
+            </Checkpoint>
+
+            {/* Third exchange after checkpoint */}
+            <Message>
+              <MessageAvatar src="" fallback="U" alt="User" />
+              <MessageContent>
+                Now help me think about error handling. What's a good error response format?
+              </MessageContent>
+            </Message>
+
+            <Message>
+              <MessageAvatar src="" fallback="AI" alt="Assistant" />
+              <div class="flex-1 space-y-2">
+                <MessageContent markdown>
+{`Use a consistent error envelope inspired by the **RFC 7807 Problem Details** spec:
+
+\`\`\`typescript
+interface ApiError {
+  status: number;        // HTTP status code
+  code: string;          // Machine-readable error code
+  message: string;       // Human-readable description
+  details?: unknown[];   // Validation errors, field-level info
+  requestId: string;     // For debugging/support
+}
+
+// Example responses
+// 400 Bad Request
+{
+  "status": 400,
+  "code": "VALIDATION_ERROR",
+  "message": "Invalid task data",
+  "details": [
+    { "field": "title", "error": "Required field missing" },
+    { "field": "dueDate", "error": "Must be a future date" }
+  ],
+  "requestId": "req_abc123"
+}
+
+// 404 Not Found
+{
+  "status": 404,
+  "code": "RESOURCE_NOT_FOUND",
+  "message": "Task not found",
+  "requestId": "req_def456"
+}
+\`\`\`
+
+Always include the \`requestId\` -- it's invaluable for correlating client errors with server logs.`}
+                </MessageContent>
+                <MessageActions>
+                  <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
+                  <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
+                  <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
+                </MessageActions>
+              </div>
+            </Message>
+
+            <ChatContainerScrollAnchor />
+          </ChatContainerContent>
+        </ChatContainer>
+
+        <div class="px-4 pb-4">
+          <PromptInput>
+            <PromptInputTextarea placeholder="Continue the API design..." />
+            <PromptInputActions class="justify-end">
+              <Button variant="default" size="icon-sm" class="rounded-full">
+                <ArrowUp class="size-4" />
+              </Button>
+            </PromptInputActions>
+          </PromptInput>
+        </div>
+      </div>
+    );
+  },
+};

package/src/stories/context-usage.stories.tsx

@@ -0,0 +1,155 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import {
+  Context, ContextTrigger, ContextContent,
+  ContextContentHeader, ContextContentBody, ContextContentFooter,
+  ContextInputUsage, ContextOutputUsage, ContextReasoningUsage, ContextCacheUsage,
+  ModelSwitcher, Button, Separator,
+} from '../index';
+import type { ModelOption } from '../types';
+import { createSignal } from 'solid-js';
+
+const meta: Meta = {
+  title: 'Examples/Context & Token Usage',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const LowUsage: Story = {
+  name: 'Low Usage (Green)',
+  render: () => (
+    <div class="p-8">
+      <p class="text-sm text-muted-foreground mb-4">Early in a conversation -- minimal token usage.</p>
+      <Context usedTokens={4200} maxTokens={200000} inputTokens={2800} outputTokens={1400} estimatedCost={0.012}>
+        <ContextTrigger />
+        <ContextContent>
+          <ContextContentHeader />
+          <ContextContentBody>
+            <div class="space-y-1.5">
+              <ContextInputUsage />
+              <ContextOutputUsage />
+            </div>
+          </ContextContentBody>
+          <ContextContentFooter />
+        </ContextContent>
+      </Context>
+    </div>
+  ),
+};
+
+export const MediumUsage: Story = {
+  name: 'Medium Usage (Yellow)',
+  render: () => (
+    <div class="p-8">
+      <p class="text-sm text-muted-foreground mb-4">Extended conversation with reasoning -- approaching 75% usage.</p>
+      <Context usedTokens={150000} maxTokens={200000} inputTokens={85000} outputTokens={42000} reasoningTokens={23000} estimatedCost={0.89}>
+        <ContextTrigger />
+        <ContextContent>
+          <ContextContentHeader />
+          <ContextContentBody>
+            <div class="space-y-1.5">
+              <ContextInputUsage />
+              <ContextOutputUsage />
+              <ContextReasoningUsage />
+            </div>
+          </ContextContentBody>
+          <ContextContentFooter />
+        </ContextContent>
+      </Context>
+    </div>
+  ),
+};
+
+export const HighUsage: Story = {
+  name: 'High Usage (Red)',
+  render: () => (
+    <div class="p-8">
+      <p class="text-sm text-muted-foreground mb-4">Near the context limit -- user should consider starting a new conversation.</p>
+      <Context usedTokens={189000} maxTokens={200000} inputTokens={110000} outputTokens={54000} reasoningTokens={25000} estimatedCost={1.42}>
+        <ContextTrigger />
+        <ContextContent>
+          <ContextContentHeader />
+          <ContextContentBody>
+            <div class="space-y-1.5">
+              <ContextInputUsage />
+              <ContextOutputUsage />
+              <ContextReasoningUsage />
+            </div>
+          </ContextContentBody>
+          <ContextContentFooter />
+        </ContextContent>
+      </Context>
+    </div>
+  ),
+};
+
+export const WithCacheBreakdown: Story = {
+  name: 'Full Breakdown with Cache',
+  render: () => (
+    <div class="p-8">
+      <p class="text-sm text-muted-foreground mb-4">Detailed usage including cache hit tokens.</p>
+      <Context usedTokens={82000} maxTokens={200000} inputTokens={45000} outputTokens={22000} reasoningTokens={15000} cacheTokens={32000} estimatedCost={0.38}>
+        <ContextTrigger />
+        <ContextContent>
+          <ContextContentHeader />
+          <ContextContentBody>
+            <div class="space-y-1.5">
+              <ContextInputUsage />
+              <ContextOutputUsage />
+              <ContextReasoningUsage />
+              <ContextCacheUsage />
+            </div>
+          </ContextContentBody>
+          <ContextContentFooter />
+        </ContextContent>
+      </Context>
+    </div>
+  ),
+};
+
+export const InHeaderBar: Story = {
+  name: 'In a Header Bar',
+  render: () => {
+    const [modelId, setModelId] = createSignal('claude-4');
+    const models: ModelOption[] = [
+      { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+      { id: 'claude-4-sonnet', name: 'Claude 4 Sonnet', provider: 'Anthropic' },
+    ];
+
+    return (
+      <div class="w-full max-w-3xl">
+        <p class="text-sm text-muted-foreground mb-4 px-4">Context usage as it appears in the app header, alongside model switcher.</p>
+
+        <div class="bg-background rounded-xl shadow-lg overflow-hidden">
+          <div class="flex items-center justify-between px-4 py-2.5">
+            <div class="flex items-center gap-3">
+              <h2 class="text-sm font-semibold text-foreground">Database indexing strategies</h2>
+              <span class="text-xs text-muted-foreground">24 messages</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <ModelSwitcher models={models} currentModelId={modelId()} onModelChange={setModelId} />
+              <Context usedTokens={67000} maxTokens={200000} inputTokens={38000} outputTokens={29000} estimatedCost={0.31}>
+                <ContextTrigger />
+                <ContextContent>
+                  <ContextContentHeader />
+                  <ContextContentBody>
+                    <div class="space-y-1.5">
+                      <ContextInputUsage />
+                      <ContextOutputUsage />
+                    </div>
+                  </ContextContentBody>
+                  <ContextContentFooter />
+                </ContextContent>
+              </Context>
+            </div>
+          </div>
+          <Separator />
+          <div class="h-48 flex items-center justify-center text-muted-foreground text-sm">
+            Chat content area
+          </div>
+        </div>
+      </div>
+    );
+  },
+};

package/src/stories/conversation-with-reasoning.stories.tsx

@@ -0,0 +1,151 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import {
+  ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageAvatar, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger, ChainOfThoughtContent, ChainOfThoughtItem,
+  Button, Separator,
+} from '../index';
+import { Copy, ThumbsUp, ThumbsDown, ArrowUp, Lightbulb, Search, Calculator } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Examples/Conversation with Reasoning',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <div class="flex flex-col h-[700px] w-full max-w-2xl bg-background rounded-xl shadow-lg overflow-hidden">
+      <div class="flex items-center px-4 py-3">
+        <h2 class="text-sm font-semibold text-foreground">Architecture Decision</h2>
+      </div>
+      <Separator />
+
+      <ChatContainer class="flex-1 p-4">
+        <ChatContainerContent class="space-y-6 py-4">
+
+          <Message>
+            <MessageAvatar src="" fallback="U" alt="User" />
+            <MessageContent>
+              I have a Chrome extension that needs to sync user data across devices. Should I use Chrome's built-in storage.sync API or implement my own sync layer with a backend? The data is about 50KB per user, updated frequently (every few minutes), and includes nested objects with arrays.
+            </MessageContent>
+          </Message>
+
+          <Message>
+            <MessageAvatar src="" fallback="AI" alt="Assistant" />
+            <div class="flex-1 space-y-3">
+
+              {/* Chain of thought reasoning */}
+              <ChainOfThought>
+                <ChainOfThoughtStep>
+                  <ChainOfThoughtTrigger leftIcon={<Search class="size-3.5" />}>
+                    Analyzing data size and sync limits
+                  </ChainOfThoughtTrigger>
+                  <ChainOfThoughtContent>
+                    <ChainOfThoughtItem>
+                      chrome.storage.sync has a total limit of 102,400 bytes and 512 items max. At 50KB per user, that's within the total limit but leaves little headroom. Each item is capped at 8,192 bytes, so nested objects would need splitting. Write operations are throttled to 120/minute in normal mode, 1,800/hour.
+                    </ChainOfThoughtItem>
+                  </ChainOfThoughtContent>
+                </ChainOfThoughtStep>
+
+                <ChainOfThoughtStep>
+                  <ChainOfThoughtTrigger leftIcon={<Calculator class="size-3.5" />}>
+                    Evaluating update frequency constraints
+                  </ChainOfThoughtTrigger>
+                  <ChainOfThoughtContent>
+                    <ChainOfThoughtItem>
+                      "Updated every few minutes" means roughly 20-30 writes per hour. That's well within the 1,800/hour limit. But if the data has nested objects with arrays, each update might need to write multiple storage items (due to the 8KB per-item limit), multiplying the write count. 50KB / 8KB = ~7 items minimum, so 7 * 30 = 210 writes/hour. Still within limits.
+                    </ChainOfThoughtItem>
+                  </ChainOfThoughtContent>
+                </ChainOfThoughtStep>
+
+                <ChainOfThoughtStep>
+                  <ChainOfThoughtTrigger leftIcon={<Lightbulb class="size-3.5" />}>
+                    Considering conflict resolution
+                  </ChainOfThoughtTrigger>
+                  <ChainOfThoughtContent>
+                    <ChainOfThoughtItem>
+                      Chrome storage.sync uses last-write-wins. For nested objects updated from multiple devices simultaneously, this could cause data loss. If a user has the extension open on laptop and desktop, and both modify different array elements, the last write overwrites the other's changes. A custom backend could use CRDTs or operational transforms for proper merging.
+                    </ChainOfThoughtItem>
+                  </ChainOfThoughtContent>
+                </ChainOfThoughtStep>
+
+                <ChainOfThoughtStep isLast>
+                  <ChainOfThoughtTrigger leftIcon={<Lightbulb class="size-3.5" />}>
+                    Weighing implementation complexity
+                  </ChainOfThoughtTrigger>
+                  <ChainOfThoughtContent>
+                    <ChainOfThoughtItem>
+                      Custom backend means: server costs, auth, API design, offline handling, retry logic, and maintenance. Chrome storage.sync is free, built-in, handles offline automatically, and requires zero infrastructure. For a personal tool, the operational burden of a backend is significant.
+                    </ChainOfThoughtItem>
+                  </ChainOfThoughtContent>
+                </ChainOfThoughtStep>
+              </ChainOfThought>
+
+              {/* Final answer */}
+              <MessageContent markdown>
+{`Given your constraints, I'd recommend a **hybrid approach**:
+
+### Use \`chrome.storage.sync\` as primary, with a chunking strategy
+
+1. **Split your 50KB into logical chunks** -- group related data into objects under 8KB each. Use a manifest key that tracks which chunks exist and their versions.
+
+2. **Implement delta syncing** -- instead of writing the full dataset every time, only write the chunks that changed. This keeps you well under rate limits.
+
+3. **Add a simple conflict guard** -- store a \`lastModifiedBy\` device ID and timestamp in each chunk. On read, if you detect a conflict, merge arrays by union rather than overwrite.
+
+\`\`\`typescript
+interface SyncChunk {
+  version: number;
+  deviceId: string;
+  updatedAt: number;
+  data: Record<string, unknown>;
+}
+
+// Write only changed chunks
+async function syncChunks(changes: Map<string, SyncChunk>) {
+  const batch: Record<string, SyncChunk> = {};
+  for (const [key, chunk] of changes) {
+    batch[\`chunk_\${key}\`] = { ...chunk, version: chunk.version + 1 };
+  }
+  await chrome.storage.sync.set(batch);
+}
+\`\`\`
+
+### When to upgrade to a backend
+
+Move to a custom sync layer if:
+- Data grows beyond **80KB** (hitting limits)
+- You need **real-time collaboration** (multiple devices editing simultaneously)
+- You want **version history** or undo across devices
+- You add team/sharing features`}
+              </MessageContent>
+
+              <MessageActions>
+                <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
+              </MessageActions>
+            </div>
+          </Message>
+
+          <ChatContainerScrollAnchor />
+        </ChatContainerContent>
+      </ChatContainer>
+
+      <div class="px-4 pb-4">
+        <PromptInput>
+          <PromptInputTextarea placeholder="Ask a follow-up..." />
+          <PromptInputActions class="justify-end">
+            <Button variant="default" size="icon-sm" class="rounded-full">
+              <ArrowUp class="size-4" />
+            </Button>
+          </PromptInputActions>
+        </PromptInput>
+      </div>
+    </div>
+  ),
+};