jivamai 0.1.4-dev.edce8f4 → 0.2.0-dev.03f9681

package/docs/guides/adding-features.md

@@ -1,196 +0,0 @@
-# Adding Features
-
-This guide walks through the full stack of changes required to add a new IPC-backed feature to Jivam. Every feature that requires main-process capabilities (file system, native APIs, jiva-core) follows this pattern.
-
----
-
-## Overview
-
-Adding a feature requires changes in four layers:
-
-```
-1. electron/ipc-handlers.ts     ← Register the IPC handler (main process)
-2. electron/preload.ts          ← Expose it on window.electron (preload bridge)
-3. src/types/electron.d.ts      ← Type the new API (TypeScript)
-4. src/store/*.store.ts         ← Consume it in a Zustand store action
-5. src/components/**/*.tsx      ← Build the UI using store + primitives
-```
-
-If the feature only touches renderer state (no IPC needed), skip steps 1–3 and add directly to a store and component.
-
----
-
-## Worked Example: Word Count Panel
-
-We'll add a panel that counts words in the currently open file.
-
-### Step 1 — IPC Handler (`electron/ipc-handlers.ts`)
-
-Add a new `ipcMain.handle` inside `setupIpcHandlers`:
-
-```typescript
-ipcMain.handle('workspace:word-count', (_event, filePath: string) => {
-  try {
-    const homeDir = os.homedir()
-    const resolvedFile = path.resolve(filePath)
-    if (!resolvedFile.startsWith(path.resolve(homeDir))) return { success: false, error: 'Access denied' }
-
-    const content = fs.readFileSync(resolvedFile, 'utf-8')
-    const wordCount = content.trim().split(/\s+/).filter(Boolean).length
-    return { success: true, wordCount }
-  } catch (err) {
-    return { success: false, error: err instanceof Error ? err.message : String(err) }
-  }
-})
-```
-
-**Convention:** Return `{ success: boolean; error?: string }` on failure. Return the data on success alongside `success: true`.
-
----
-
-### Step 2 — Preload Bridge (`electron/preload.ts`)
-
-Add the new method inside the `contextBridge.exposeInMainWorld('electron', { ... })` call, in the appropriate namespace:
-
-```typescript
-workspace: {
-  // ...existing methods...
-  wordCount: (filePath: string) =>
-    ipcRenderer.invoke('workspace:word-count', filePath),
-},
-```
-
----
-
-### Step 3 — TypeScript Types (`src/types/electron.d.ts`)
-
-Extend the `ElectronAPI` interface to include the new method:
-
-```typescript
-workspace: {
-  // ...existing methods...
-  wordCount: (filePath: string) => Promise<{
-    success: boolean
-    wordCount?: number
-    error?: string
-  }>
-}
-```
-
-After this, `window.electron.workspace.wordCount(path)` will be fully typed throughout the renderer.
-
----
-
-### Step 4 — Store Action (`src/store/files.store.ts`)
-
-Add state and an action to the relevant store:
-
-```typescript
-interface FilesState {
-  // ...existing state...
-  wordCount: number | null
-}
-
-// Inside the store:
-wordCount: null,
-
-countWords: async () => {
-  const { selectedFile } = get()
-  if (!selectedFile) return
-  const result = await window.electron.workspace.wordCount(selectedFile.path)
-  if (result.success && result.wordCount !== undefined) {
-    set({ wordCount: result.wordCount })
-  }
-},
-```
-
----
-
-### Step 5 — Component (`src/components/files/WordCountBadge.tsx`)
-
-Build the UI using store state and design system primitives:
-
-```tsx
-import { useFilesStore } from '../../store/files.store'
-import { Badge } from '../ui/Badge'
-
-export function WordCountBadge() {
-  const { wordCount, countWords, selectedFile } = useFilesStore()
-
-  useEffect(() => {
-    if (selectedFile) countWords()
-  }, [selectedFile, countWords])
-
-  if (!wordCount) return null
-
-  return (
-    <Badge variant="default">
-      {wordCount.toLocaleString()} words
-    </Badge>
-  )
-}
-```
-
----
-
-### Step 6 — Wire to AppShell or Feature Panel
-
-Add the component where it belongs in the layout:
-
-```tsx
-// In src/components/files/FilesPanel.tsx (or wherever the file preview lives):
-import { WordCountBadge } from './WordCountBadge'
-
-// In the file preview header:
-<div className="flex items-center gap-2">
-  <span className="text-sm text-[var(--text-muted)]">{selectedFile.name}</span>
-  <WordCountBadge />
-</div>
-```
-
----
-
-## Checklist
-
-Use this checklist for every new IPC-backed feature:
-
-- [ ] `ipcMain.handle('namespace:action', handler)` added in `electron/ipc-handlers.ts`
-- [ ] `namespace: { action: (...args) => ipcRenderer.invoke(...) }` added in `electron/preload.ts`
-- [ ] Type added to `ElectronAPI` in `src/types/electron.d.ts`
-- [ ] Store action added that calls `window.electron.namespace.action()`
-- [ ] Component uses `useXxxStore()` — no direct `window.electron` calls in components
-- [ ] UI uses `Button` / `Badge` primitives (no raw `<button>`)
-- [ ] Colors use CSS custom properties (no hardcoded hex)
-- [ ] Errors handled gracefully — store sets an error state or shows a toast
-- [ ] `npx tsc --noEmit` passes with zero errors
-
----
-
-## File-Only Features (No IPC)
-
-For purely UI features (e.g. a collapsible sidebar section, a new settings toggle):
-
-1. Add state to the relevant store if needed
-2. Build the component
-3. Import and render it in the appropriate parent
-
-No IPC or preload changes needed.
-
----
-
-## Adding a New Tab
-
-To add a new top-level tab to the app:
-
-1. Add the tab name to the `ActiveTab` union in `src/App.tsx`
-2. Add a `TabButton` entry in `src/components/layout/AppShell.tsx` (sidebar nav)
-3. Add a conditional render of the new panel in `AppShell`'s main content area
-4. Create the panel component in `src/components/<feature>/`
-
----
-
-## Security Considerations
-
-- **File system access:** All file paths passed to main-process handlers must be validated against `os.homedir()`. See the `workspace:list-files` and `workspace:read-file` handlers for the pattern.
-- **No shell injection:** Never interpolate user input into `execSync` strings. Use argument arrays.
-- **Config writes:** Always read the existing config with `readConfig()` before writing — never overwrite with a partial object.

package/docs/guides/design-guide.md

@@ -1,308 +0,0 @@
-# Design Guide
-
-This guide documents Jivam's visual design system: color tokens, typography, spacing, component library, animation patterns, and special CSS utilities. Follow these conventions for all new UI work to maintain visual consistency.
-
----
-
-## Color System
-
-Colors are defined as CSS custom properties in `src/index.css`. The theme is toggled by setting `data-theme="dark"` on `<html>` — controlled by `useSettingsStore`.
-
-**Never hardcode color values.** Always use the tokens below.
-
-### Design Tokens
-
-| Token | Light | Dark | Usage |
-|-------|-------|------|-------|
-| `--bg` | `#F5F3FF` | `#0A0A0B` | Page background |
-| `--bg-secondary` | `#EDE9FE` | `#111113` | Secondary background areas |
-| `--card` | `#FFFFFF` | `rgba(28,28,33,0.85)` | Card and panel surfaces |
-| `--card-border` | `rgba(139,92,246,0.15)` | `rgba(139,92,246,0.20)` | Card borders |
-| `--card-shadow` | `0 4px 24px rgba(139,92,246,0.08)` | `0 4px 24px rgba(139,92,246,0.15)` | Card shadows |
-| `--text` | `#1E1B4B` | `#F5F3FF` | Primary text |
-| `--text-muted` | `#6B7280` | `#9CA3AF` | Secondary / supporting text |
-| `--text-subtle` | `#9CA3AF` | `#6B7280` | Placeholder and hint text |
-| `--accent` | `#8B5CF6` | `#A78BFA` | Primary brand accent |
-| `--accent-blue` | `#3B82F6` | `#60A5FA` | Secondary accent |
-| `--accent-indigo` | `#6366F1` | `#818CF8` | Tertiary accent |
-| `--input-bg` | `rgba(255,255,255,0.9)` | `rgba(28,28,33,0.9)` | Input field backgrounds |
-| `--input-border` | `rgba(139,92,246,0.25)` | `rgba(139,92,246,0.35)` | Input borders |
-| `--user-bubble-bg` | `linear-gradient(135deg,#8B5CF6,#3B82F6)` | `linear-gradient(135deg,#7C3AED,#2563EB)` | User message bubbles |
-| `--agent-bubble-bg` | `#FFFFFF` | `rgba(28,28,33,0.9)` | Assistant message bubbles |
-| `--agent-bubble-border` | `rgba(139,92,246,0.12)` | `rgba(139,92,246,0.20)` | Assistant bubble borders |
-| `--topbar-bg` | `rgba(245,243,255,0.85)` | `rgba(10,10,11,0.9)` | Top bar background |
-| `--topbar-border` | `rgba(139,92,246,0.12)` | `rgba(139,92,246,0.15)` | Top bar bottom border |
-| `--sidebar-bg` | `rgba(255,255,255,0.95)` | `rgba(17,17,19,0.98)` | Sidebar background |
-| `--scrollbar-thumb` | `rgba(139,92,246,0.3)` | `rgba(139,92,246,0.4)` | Scrollbar handle |
-| `--code-bg` | `#F8F5FF` | `rgba(28,28,33,0.8)` | Code block background |
-| `--code-border` | `rgba(139,92,246,0.12)` | `rgba(139,92,246,0.20)` | Code block border |
-
-### Brand Colors (Fixed, Theme-Independent)
-
-These are in `tailwind.config.js` and can be used as Tailwind classes:
-
-| Name | Hex | Tailwind class example |
-|------|-----|----------------------|
-| `jivam-purple` | `#8B5CF6` | `bg-jivam-purple`, `text-jivam-purple` |
-| `jivam-blue` | `#3B82F6` | `bg-jivam-blue`, `text-jivam-blue` |
-
----
-
-## Typography
-
-**Font:** `Inter` — loaded from Google Fonts in `src/index.css`. Fallback: `system-ui, sans-serif`.
-
-```css
-font-family: 'Inter', system-ui, sans-serif;
-```
-
-**Weights used:** 300 (light), 400 (regular), 500 (medium), 600 (semibold), 700 (bold).
-
-**Scale:** Tailwind defaults. Common usage:
-
-| Class | Size | Use |
-|-------|------|-----|
-| `text-xs` | 12px | Badges, captions, metadata |
-| `text-sm` | 14px | Body text, list items, labels |
-| `text-base` | 16px | Default (rarely used explicitly) |
-| `text-lg` | 18px | Section headings |
-| `text-2xl` | 24px | Screen titles (h1 in setup/splash) |
-
-**Gradient text** — for brand headings only:
-
-```html
-<h1 class="gradient-text">Jivam</h1>
-```
-
-```css
-.gradient-text {
-  background: linear-gradient(135deg, var(--accent), var(--accent-blue));
-  -webkit-background-clip: text;
-  -webkit-text-fill-color: transparent;
-}
-```
-
----
-
-## Spacing & Layout
-
-**App layout:** Fixed sidebar (240px) + `flex-1` main content area. Do not change these dimensions.
-
-**Spacing scale:** Use Tailwind's scale. Preferred values:
-
-| Use case | Class |
-|----------|-------|
-| Tight gap (icons, inline) | `gap-1`, `gap-2` |
-| Standard gap (list items, cards) | `gap-3`, `gap-4` |
-| Section spacing | `gap-6`, `gap-8` |
-| Card padding | `p-4`, `px-4 py-3` |
-| Panel padding | `p-6` |
-
-**Border radius:** Prefer `rounded-xl` (12px) for cards and panels. Use `rounded-lg` for buttons and inputs. Use `rounded-full` only for avatars and dots.
-
----
-
-## Utility Classes
-
-These are defined in `src/index.css` and must be used as intended.
-
-### `.glass-card`
-
-The standard card surface. Applied to all floating panels, settings cards, and sidebar sections.
-
-```css
-.glass-card {
-  background: var(--card);
-  backdrop-filter: blur(12px);
-  -webkit-backdrop-filter: blur(12px);
-  border: 1px solid var(--card-border);
-  box-shadow: var(--card-shadow);
-}
-```
-
-Usage: `<div className="glass-card rounded-xl p-4">`
-
-### `.aurora-bg`
-
-The animated purple-blue gradient orbs that appear behind all screens. **Always include on every top-level screen** — it is part of the brand identity.
-
-```html
-<div className="aurora-bg" />
-```
-
-It is `position: fixed; inset: 0; pointer-events: none; z-index: 0`. Content must have `position: relative; z-index: 10` (or higher) to appear above it.
-
-### `.gradient-text`
-
-See Typography section above.
-
-### `.typing-dot`
-
-Three animated dots used as a loading indicator:
-
-```html
-<div className="flex items-center gap-1.5">
-  <span className="typing-dot" />
-  <span className="typing-dot" />
-  <span className="typing-dot" />
-</div>
-```
-
-Dots bounce with staggered delays. Color uses `var(--accent)`.
-
-### `.drag-region` / `.no-drag`
-
-Controls Electron window dragging. Apply `.drag-region` to the title bar area. Apply `.no-drag` to interactive elements within a drag region (buttons, inputs).
-
-### `.markdown-body`
-
-Applied to AI response content. Provides scoped prose styles for `h1-h4`, `p`, `ul/ol`, `code`, `pre`, `blockquote`, `table`, `a`, and `hr`. Uses `var(--code-bg)` and `var(--code-border)` for code blocks.
-
----
-
-## Component Library
-
-All interactive components live in `src/components/ui/`. **Always use these primitives — never write raw `<button>` or bare `<span>` elements in feature components.**
-
-### `Button`
-
-```tsx
-import { Button } from '../ui/Button'
-
-<Button variant="primary" size="md" onClick={handler}>
-  <Icon size={14} />
-  Label
-</Button>
-```
-
-| Prop | Values | Default |
-|------|--------|---------|
-| `variant` | `primary` \| `secondary` \| `ghost` \| `danger` | `secondary` |
-| `size` | `sm` \| `md` \| `lg` | `md` |
-| `disabled` | `boolean` | `false` |
-
-- `primary` — filled with `--accent` gradient, white text
-- `secondary` — outlined with `--card-border`, `--text` text
-- `ghost` — no border, transparent background, `--text-muted` text
-- `danger` — red accent, used for destructive actions only
-
-### `Badge`
-
-```tsx
-import { Badge } from '../ui/Badge'
-
-<Badge variant="success">Connected</Badge>
-```
-
-| Prop | Values |
-|------|--------|
-| `variant` | `default` \| `success` \| `warning` \| `danger` \| `accent` |
-
----
-
-## Animations (Framer Motion)
-
-Jivam uses [Framer Motion](https://www.framer.com/motion/) for all transitions. Do not use CSS `transition` for enter/exit — use `AnimatePresence` + `motion.*`.
-
-### Standard Page Entrance
-
-```tsx
-<motion.div
-  initial={{ opacity: 0, y: 16 }}
-  animate={{ opacity: 1, y: 0 }}
-  transition={{ duration: 0.4 }}
->
-```
-
-### Staggered List Items
-
-```tsx
-{items.map((item, index) => (
-  <motion.div
-    key={item.id}
-    initial={{ opacity: 0, y: 8 }}
-    animate={{ opacity: 1, y: 0 }}
-    transition={{ delay: index * 0.08 }}
-  >
-```
-
-### Collapse / Expand (Height Animation)
-
-```tsx
-<AnimatePresence>
-  {expanded && (
-    <motion.div
-      initial={{ height: 0, opacity: 0 }}
-      animate={{ height: 'auto', opacity: 1 }}
-      exit={{ height: 0, opacity: 0 }}
-      transition={{ duration: 0.2 }}
-    >
-```
-
-### Brand Pulse (Logo, Loading States)
-
-```tsx
-<motion.div
-  animate={{ scale: [1, 1.04, 1] }}
-  transition={{ duration: 2.5, repeat: Infinity, ease: 'easeInOut' }}
->
-```
-
-### Exit Transitions
-
-Always wrap components that mount/unmount with `AnimatePresence` at the parent level:
-
-```tsx
-<AnimatePresence>
-  {showPanel && (
-    <motion.div
-      initial={{ opacity: 0 }}
-      animate={{ opacity: 1 }}
-      exit={{ opacity: 0 }}
-    >
-```
-
----
-
-## Scrollbars
-
-Scrollbars are globally styled in `src/index.css`:
-
-- Width: 6px
-- Thumb: `var(--scrollbar-thumb)` (accent purple at 30-40% opacity)
-- Track: transparent
-- Hover: accent at 50% opacity
-
-No additional classes needed — all scrollable elements inherit this automatically.
-
----
-
-## Syntax Highlighting
-
-Code blocks in AI responses use [highlight.js](https://highlightjs.org/). Theme overrides are in `src/index.css` under `.hljs`. Dark mode applies custom token colors:
-
-| Token | Dark color |
-|-------|-----------|
-| Keywords | `#C084FC` (purple) |
-| Strings | `#86EFAC` (green) |
-| Comments | `#6B7280` (gray) |
-| Numbers | `#FCA5A5` (red) |
-| Functions | `#93C5FD` (blue) |
-
----
-
-## Do's and Don'ts
-
-**Do:**
-- Use CSS custom properties for all colors
-- Use `.glass-card` for all card surfaces
-- Use `Button` and `Badge` primitives for all interactive elements
-- Include `<div className="aurora-bg" />` on every full-screen view
-- Use Framer Motion for enter/exit animations
-
-**Don't:**
-- Hardcode hex colors (use tokens)
-- Write raw `<button>` elements
-- Use CSS `display: none` for hiding — use `AnimatePresence` + conditional rendering
-- Skip the aurora background on new screens
-- Add scrollbar styles to individual elements (global styles handle it)