jivamai 0.1.4-dev.63d462c

package/docs/guides/adding-features.md

@@ -0,0 +1,196 @@
+# 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

@@ -0,0 +1,308 @@
+# 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)

package/electron-builder.yml

@@ -0,0 +1,86 @@
+appId: ai.karmaloop.jivam
+productName: Jivam
+copyright: Copyright © 2026 Karmaloop AI
+
+directories:
+  output: release
+  buildResources: assets
+
+files:
+  - dist/**/*
+  - dist-electron/**/*
+  - package.json
+
+asar: true
+
+mac:
+  category: public.app-category.productivity
+  icon: assets/icon.icns
+  minimumSystemVersion: "13.0"
+  target:
+    - target: dmg
+      arch: universal
+    - target: zip
+      arch: universal
+  darkModeSupport: true
+  # Code signing — uncomment and set env vars when Apple Developer certificate is ready:
+  # notarize:
+  #   teamId: ${APPLE_TEAM_ID}
+
+dmg:
+  title: "Jivam ${version}"
+  contents:
+    - x: 130
+      y: 220
+    - x: 410
+      y: 220
+      type: link
+      path: /Applications
+  window:
+    width: 540
+    height: 380
+
+win:
+  icon: assets/icon.png
+  target:
+    - target: nsis
+      arch:
+        - x64
+        - arm64
+    - target: portable
+      arch: x64
+  # Azure Trusted Signing — uncomment and set env vars when certificate is ready:
+  # azureSignOptions:
+  #   endpoint: ${AZURE_SIGNING_ENDPOINT}
+  #   certificateProfileName: ${AZURE_CERT_PROFILE_NAME}
+  #   codeSigningAccountName: ${AZURE_SIGNING_ACCOUNT_NAME}
+
+nsis:
+  artifactName: ${productName}-Setup-${version}.exe
+  oneClick: false
+  perMachine: false                    # install to %LocalAppData% — no UAC elevation needed
+  allowToChangeInstallationDirectory: true
+  createDesktopShortcut: true
+  createStartMenuShortcut: true
+
+portable:
+  artifactName: ${productName}-${version}-portable.exe
+
+appImage:
+  artifactName: ${productName}-${version}-${arch}.AppImage
+
+linux:
+  icon: assets/icon.png
+  category: Utility
+  target:
+    - target: AppImage
+      arch:
+        - x64
+        - arm64
+    - target: deb
+      arch: x64
+
+publish:
+  provider: github
+  owner: KarmaloopAI
+  repo: JivamAI

package/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; connect-src 'self' ws://localhost:* wss://localhost:* http://localhost:* https:; img-src 'self' data: blob:;" />
+    <meta name="theme-color" content="#8b5cf6" />
+    <link rel="manifest" href="/manifest.json" />
+    <title>Jivam</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "jivamai",
+  "version": "0.1.4-dev.63d462c",
+  "description": "Jivam - Desktop UI for the Jiva autonomous AI agent",
+  "main": "dist-server/index.js",
+  "bin": {
+    "jivam": "bin/jivam.js"
+  },
+  "scripts": {
+    "dev": "concurrently \"vite\" \"cross-env NODE_ENV=development tsx server/index.ts\"",
+    "build": "vite build && vite build --config vite.server.config.ts",
+    "start": "node dist-server/index.js",
+    "preview": "vite preview"
+  },
+  "keywords": [],
+  "author": {
+    "name": "Karmaloop AI",
+    "email": "achatterjee@gritsa.com"
+  },
+  "license": "MIT",
+  "jivaCompatibleVersion": "0.3.44",
+  "dependencies": {
+    "@tanstack/react-virtual": "^3.14.5",
+    "clsx": "^2.1.1",
+    "electron-updater": "^6.3.9",
+    "express": "^5.2.1",
+    "framer-motion": "^11.18.2",
+    "highlight.js": "^11.11.1",
+    "lucide-react": "^0.462.0",
+    "multer": "^2.2.0",
+    "open": "^11.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-markdown": "^9.1.0",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^2.6.1",
+    "ws": "^8.21.0",
+    "zustand": "^4.5.7"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/multer": "^2.2.0",
+    "@types/node": "^22.19.11",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@types/ws": "^8.18.1",
+    "@vitejs/plugin-react": "^4.7.0",
+    "autoprefixer": "^10.4.24",
+    "concurrently": "^10.0.3",
+    "cross-env": "^7.0.3",
+    "electron": "^33.4.11",
+    "electron-builder": "^25.1.8",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.19",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.21",
+    "vite-plugin-electron": "^0.28.8",
+    "vite-plugin-electron-renderer": "^0.14.6"
+  }
+}