@cryptiklemur/lattice 1.16.2 → 1.16.4

package/CLAUDE.md

@@ -1,35 +1,52 @@
-# Lattice — Project Rules
+# CLAUDE.md
 
-## Icons
-- Use `lucide-react` for ALL icons. Never write custom/inline SVG icons.
-- Import icons individually: `import { Settings, Moon, Sun } from "lucide-react"`
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Structure
+Bun monorepo with three workspaces:
+- `shared/` — TypeScript types and constants (no build, imported directly)
+- `server/` — Bun daemon serving WebSocket API + static client assets on port 7654
+- `client/` — React 19 + Vite + Tailwind + daisyUI web app
+
+## Commands
+- `bun run dev` — starts server (--watch) + Vite dev server, hot reloads both
+- `bun run build` — builds all workspaces (only client produces output)
+- `bun run typecheck` — runs tsc across all workspaces
+- `bunx playwright test` — runs Playwright tests (server must be running on :7654)
+- Single test: `bunx playwright test tests/session-flow.spec.ts`
 
 ## Coding Standards
-- Use `var` instead of `const`/`let`. No arrow functions.
-- Server-side: ESM with Bun. Client-side: ESM with Vite + React.
-- No emojis for icons or in UI.
+- Use `const`/`let` (not `var`). Use named function declarations, not arrow functions — except for anonymous callbacks where arrows are fine.
+- No emojis for icons or in UI. Use `lucide-react` for all icons.
 - No section separator comments or organizational comments.
-- One class per file.
 - Follow .editorconfig (2-space indent, LF, UTF-8).
+- Server: ESM with Bun. Client: ESM with Vite + React.
 
 ## Git
 - Never add "Co-Authored-By" lines mentioning Claude/AI.
-- Commit messages follow Angular Commit Convention.
+- Commit messages follow Angular Commit Convention (feat/fix/refactor/etc).
 - Only commit when explicitly asked.
+- Releases are automated via semantic-release on push to main.
 
-## Development
-- Use `bun run dev` to start the development server — it hot reloads both the server and the web app automatically. No manual restart needed after code changes.
+## Design
+See `.impeccable.md` for comprehensive design guidelines. Key constraints:
+- Dark-first with 23 base16 themes via OKLCH CSS variables
+- Tailwind + daisyUI component framework
+- Typography: JetBrains Mono (headings/code), IBM Plex Sans (body)
+- Three surface tiers: Chrome (base-200), Stage (base-100 + dot-grid), Elevated (base-300 + shadow)
+- Never hardcode colors — always use CSS variables/theme tokens
+- WCAG AA contrast, prefers-reduced-motion, keyboard-first
 
 ## Pre-existing Errors
-- DO NOT EVER LEAVE PRE-EXISTING ERRORS, FIX THEM.
-
-## Design Context
-See `.impeccable.md` for comprehensive design guidelines. Key principles:
-- **Personality**: Precise, Technical, Calm — quiet authority, no fluff
-- **Emotions**: Control & Mastery, Trust & Reliability
-- **Dark-first** with 23 base16 themes via OKLCH color space
-- **Typography**: JetBrains Mono (headings/code), IBM Plex Sans (body)
-- **Three surface tiers**: Chrome (base-200), Stage (base-100 + dot-grid), Elevated (base-300 + shadow)
-- **Design principles**: Earn every pixel, quiet confidence, state is sacred, dense but breathable, theme-native
-- **Accessibility**: WCAG AA, reduced motion, high contrast, color blind safe, mobile/responsive, keyboard-first
-- **Anti-patterns**: No gratuitous animation, no emoji icons, no hardcoded colors, no "AI slop" aesthetics
+DO NOT EVER LEAVE PRE-EXISTING ERRORS. FIX THEM.
+
+## Environment
+- ANTHROPIC_API_KEY is optional — server uses the token from `claude setup-token` if not set.
+- Server binds to 0.0.0.0:7654 (WSL2 compatible).
+- Client dev server runs on :5173 but production serves from server via client/dist/.
+
+## Testing
+- Playwright tests live in `tests/` at the project root.
+- Tests require the server running on localhost:7654.
+- Screenshots on failure go to `test-results/`.
+- Use Playwright MCP for visual verification. Save screenshots to `.playwright-mcp/`.

package/README.md

@@ -1,23 +1,52 @@
 # Lattice
 
-Multi-machine agentic dashboard for Claude Code. Monitor sessions, manage MCP servers and skills, orchestrate across mesh-networked nodes.
+Multi-machine agentic dashboard for Claude Code. Monitor sessions, manage projects, track costs, and orchestrate across mesh-networked nodes.
 
 > **Alpha** — Lattice is under active development. APIs and features may change.
 
+![Dashboard](docs/screenshots/dashboard.png)
+
 ## What is Lattice?
 
-Lattice is a web dashboard that sits alongside your Claude Code sessions. It gives you a unified view across projects, machines, and sessions — with real-time monitoring, configuration management, and a skill marketplace.
+Lattice is a web dashboard that sits alongside your Claude Code sessions. It gives you a unified view across projects, machines, and sessions — with real-time monitoring, cost tracking, and configuration management.
+
+### Core Features
+
+- **Multi-project dashboard** — Fleet overview with node status, session counts, cost stats, and recent activity across all projects
+- **Real-time chat** — Send messages, approve tool use, monitor context window usage and costs with per-message token counts
+- **Session management** — Browse, rename, delete, search, and resume sessions with date range filtering and hover previews
+- **Analytics** — Cost over time, token flow, cache efficiency, session complexity, activity calendar, and 15+ chart types
+- **Cost budget** — Daily spend tracking with configurable enforcement (warning, confirm, or hard block)
+- **Theme system** — 23 base16 themes (12 dark, 11 light) with OKLCH color space for perceptual consistency
+
+![Chat View](docs/screenshots/chat-view.png)
+
+### Productivity
+
+- **Session tabs** — Open multiple sessions as tabs, switch between them, split-pane via right-click
+- **Message bookmarks** — Pin important messages, jump between bookmarks, global bookmarks view across all sessions
+- **Keyboard shortcuts** — Press `?` to see all shortcuts, `Ctrl+K` for command palette
+- **Message actions** — Copy messages (raw markdown or plain text), start new sessions from any message
+- **Auto-titling** — Sessions automatically get descriptive titles from the first exchange
+- **Session hover previews** — Hover any session to see cost, duration, message count, model, and last message
 
-### Features
+![Analytics](docs/screenshots/analytics.png)
 
-- **Multi-project dashboard** — See recent sessions across all projects at a glance, jump back into any conversation
-- **MCP server management** — Add, edit, and remove MCP servers at global or project level through a visual editor
-- **Skill marketplace** — Search and install skills from [skills.sh](https://skills.sh), manage installed skills with rendered markdown previews
-- **Mesh networking** — Connect multiple machines into a mesh network, see node status and project distribution
-- **Session management** — Browse, rename, delete, and resume Claude Code sessions per project
-- **Real-time chat** — Send messages, approve tool use, monitor context usage and costs
-- **Theme system** — 23 base16 themes (dark and light) with OKLCH color space
+### Infrastructure
+
+- **MCP server management** — Add, edit, and remove MCP servers at global or project level
+- **Skill marketplace** — Search and install skills from [skills.sh](https://skills.sh)
+- **Mesh networking** — Connect multiple machines, proxy sessions across nodes with automatic discovery
 - **Configuration editor** — Edit CLAUDE.md, environment variables, rules, and permissions through the UI
+- **Memory management** — View and edit Claude's project memories with frontmatter metadata
+
+![Settings](docs/screenshots/settings.png)
+
+### Mobile Support
+
+Responsive design with touch targets, swipe-to-open sidebar, and optimized layouts for mobile devices.
+
+<img src="docs/screenshots/mobile-chat.png" width="300" alt="Mobile chat view" />
 
 ## Quick Start
 
@@ -48,17 +77,43 @@ bun install
 bun run dev
 ```
 
+The dev server hot-reloads both the Bun server and the Vite client automatically.
+
 ## Architecture
 
-Lattice is a monorepo with three packages:
+Lattice is a Bun monorepo with three packages:
 
 | Package | Description |
 |---------|------------|
-| `shared/` | TypeScript types, message definitions, constants |
-| `server/` | Bun WebSocket server — handlers, session management, mesh networking |
-| `client/` | React + Vite dashboard — UI components, state management, themes |
+| `shared/` | TypeScript types, message protocol definitions, constants |
+| `server/` | Bun WebSocket server — session management, analytics engine, mesh networking, structured logging |
+| `client/` | React 19 + Vite + Tailwind + daisyUI — UI components, state management, 23 themes |
 
-The server communicates with clients via WebSocket using a typed message protocol defined in `shared/`. Sessions are managed through the Claude Agent SDK. The client uses Tanstack Store for state management and Tanstack Router for routing.
+The server communicates with clients via WebSocket using a typed message protocol defined in `shared/`. Sessions are managed through the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk). The client uses Tanstack Store for state and Tanstack Router for routing.
+
+### Security
+
+- Authentication via passphrase with scrypt hashing and 24-hour token expiration
+- Per-client WebSocket rate limiting (100 messages per 10-second window)
+- Attachment upload size limits (10MB max)
+- Bash `cd` commands boundary-checked against project directory
+- Mesh pairing tokens expire after 5 minutes
+- Graceful server shutdown with active stream draining
+
+### Testing
+
+Playwright test suite covering onboarding, session flow, keyboard shortcuts, accessibility, message actions, and session previews.
+
+```bash
+# Start the server first
+bun run dev
+
+# Run tests
+bunx playwright test
+
+# Single test file
+bunx playwright test tests/session-flow.spec.ts
+```
 
 ## Configuration
 
@@ -66,14 +121,20 @@ Lattice stores its config at `~/.lattice/config.json`. Global Claude settings ar
 
 | Path | Purpose |
 |------|---------|
-| `~/.lattice/config.json` | Lattice daemon config (port, name, TLS, projects) |
+| `~/.lattice/config.json` | Daemon config (port, name, TLS, projects, cost budget) |
+| `~/.lattice/bookmarks.json` | Message bookmarks across all sessions |
 | `~/.claude/CLAUDE.md` | Global Claude instructions |
 | `~/.claude.json` | Global MCP server configuration |
 | `~/.claude/skills/` | Global skills directory |
-| `~/.claude/rules/` | Global rules |
 
 Project-level settings are stored in each project's `.claude/` directory and `.mcp.json`.
 
+### Environment
+
+- `ANTHROPIC_API_KEY` — Optional. Server uses the token from `claude setup-token` if not set.
+- `DEBUG=lattice:*` — Enable structured debug logging (namespaces: server, ws, chat, session, mesh, auth, fs, analytics)
+- Server binds to `0.0.0.0:7654` by default. Override with `lattice --port <port>`.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and pull request guidelines.

package/client/src/components/analytics/charts/CacheEfficiencyChart.tsx

@@ -41,15 +41,15 @@ export function CacheEfficiencyChart({ data }: CacheEfficiencyChartProps) {
       <AreaChart data={displayData} margin={{ top: 4, right: 4, left: -20, bottom: 0 }}>
         <defs>
           <linearGradient id="cacheEffGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.success} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.success} stopOpacity={0.02} />
+            <stop offset="5%" stopColor={colors.success} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.success} stopOpacity={0.2} />
           </linearGradient>
         </defs>
         <CartesianGrid strokeDasharray="3 3" stroke={colors.gridStroke} vertical={false} />
         <XAxis dataKey="date" tick={getTickStyle()} axisLine={false} tickLine={false} />
         <YAxis domain={[0, 100]} tick={getTickStyle()} axisLine={false} tickLine={false} tickFormatter={function (v) { return v + "%"; }} />
         <Tooltip content={<CustomTooltip />} />
-        <Area type="monotone" dataKey="rate" stroke={colors.success} fill="url(#cacheEffGrad)" strokeWidth={1.5} />
+        <Area type="monotone" dataKey="rate" stroke={colors.success} fill="url(#cacheEffGrad)" strokeWidth={2} />
       </AreaChart>
     </ResponsiveContainer>
   );

package/client/src/components/analytics/charts/CostAreaChart.tsx

@@ -49,20 +49,20 @@ export function CostAreaChart({ data }: CostAreaChartProps) {
       <AreaChart data={data} margin={{ top: 4, right: 4, left: -20, bottom: 0 }}>
         <defs>
           <linearGradient id="opusGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.secondary} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.secondary} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.secondary} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.secondary} stopOpacity={0.2} />
           </linearGradient>
           <linearGradient id="sonnetGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.2} />
           </linearGradient>
           <linearGradient id="haikuGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.success} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.success} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.success} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.success} stopOpacity={0.2} />
           </linearGradient>
           <linearGradient id="otherGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.warning} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.warning} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.warning} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.warning} stopOpacity={0.2} />
           </linearGradient>
         </defs>
         <CartesianGrid strokeDasharray="3 3" stroke={colors.gridStroke} vertical={false} />

package/client/src/components/analytics/charts/CostDistributionChart.tsx

@@ -37,8 +37,8 @@ export function CostDistributionChart({ data }: CostDistributionChartProps) {
       <AreaChart data={data} margin={{ top: 4, right: 4, left: -20, bottom: 0 }}>
         <defs>
           <linearGradient id="distGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.35} />
-            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.02} />
+            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.2} />
           </linearGradient>
         </defs>
         <CartesianGrid strokeDasharray="3 3" stroke={colors.gridStroke} vertical={false} />

package/client/src/components/analytics/charts/CumulativeCostChart.tsx

@@ -37,8 +37,8 @@ export function CumulativeCostChart({ data }: CumulativeCostChartProps) {
       <AreaChart data={data} margin={{ top: 4, right: 4, left: -20, bottom: 0 }}>
         <defs>
           <linearGradient id="cumulativeGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.3} />
-            <stop offset="95%" stopColor={colors.primary} stopOpacity={0} />
+            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.7} />
+            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.15} />
           </linearGradient>
         </defs>
         <CartesianGrid strokeDasharray="3 3" stroke={colors.gridStroke} vertical={false} />

package/client/src/components/analytics/charts/TokenFlowChart.tsx

@@ -53,25 +53,25 @@ export function TokenFlowChart({ data }: TokenFlowChartProps) {
       <AreaChart data={data} margin={{ top: 4, right: 4, left: -20, bottom: 0 }}>
         <defs>
           <linearGradient id="inputGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.primary} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.primary} stopOpacity={0.25} />
           </linearGradient>
           <linearGradient id="outputGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.success} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.success} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.success} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.success} stopOpacity={0.25} />
           </linearGradient>
           <linearGradient id="cacheReadGrad" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="5%" stopColor={colors.warning} stopOpacity={0.4} />
-            <stop offset="95%" stopColor={colors.warning} stopOpacity={0.05} />
+            <stop offset="5%" stopColor={colors.warning} stopOpacity={0.8} />
+            <stop offset="95%" stopColor={colors.warning} stopOpacity={0.25} />
           </linearGradient>
         </defs>
         <CartesianGrid strokeDasharray="3 3" stroke={colors.gridStroke} vertical={false} />
         <XAxis dataKey="date" tick={getTickStyle()} axisLine={false} tickLine={false} />
         <YAxis tick={getTickStyle()} axisLine={false} tickLine={false} tickFormatter={formatTokens} />
         <Tooltip content={<CustomTooltip />} />
-        <Area type="monotone" dataKey="input" stackId="1" stroke={colors.primary} fill="url(#inputGrad)" strokeWidth={1.5} />
-        <Area type="monotone" dataKey="output" stackId="1" stroke={colors.success} fill="url(#outputGrad)" strokeWidth={1.5} />
-        <Area type="monotone" dataKey="cacheRead" stackId="1" stroke={colors.warning} fill="url(#cacheReadGrad)" strokeWidth={1.5} />
+        <Area type="monotone" dataKey="input" stackId="1" stroke={colors.primary} fill="url(#inputGrad)" strokeWidth={2} />
+        <Area type="monotone" dataKey="output" stackId="1" stroke={colors.success} fill="url(#outputGrad)" strokeWidth={2} />
+        <Area type="monotone" dataKey="cacheRead" stackId="1" stroke={colors.warning} fill="url(#cacheReadGrad)" strokeWidth={2} />
       </AreaChart>
     </ResponsiveContainer>
   );

package/client/src/hooks/useVoiceRecorder.ts

@@ -1,5 +1,34 @@
 import { useState, useCallback, useRef } from "react";
 
+interface SpeechRecognitionResult {
+  readonly transcript: string;
+  readonly confidence: number;
+  readonly isFinal: boolean;
+}
+
+interface SpeechRecognitionResultItem {
+  readonly length: number;
+  readonly isFinal: boolean;
+  item(index: number): SpeechRecognitionResult;
+  [index: number]: SpeechRecognitionResult;
+}
+
+interface SpeechRecognitionResultList {
+  readonly length: number;
+  item(index: number): SpeechRecognitionResultItem;
+  [index: number]: SpeechRecognitionResultItem;
+}
+
+interface SpeechRecognitionEvent extends Event {
+  readonly resultIndex: number;
+  readonly results: SpeechRecognitionResultList;
+}
+
+interface SpeechRecognitionErrorEvent extends Event {
+  readonly error: string;
+  readonly message: string;
+}
+
 interface SpeechRecognitionLike extends EventTarget {
   continuous: boolean;
   interimResults: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptiklemur/lattice",
-  "version": "1.16.2",
+  "version": "1.16.4",
   "description": "Multi-machine agentic dashboard for Claude Code. Monitor sessions, manage MCP servers and skills, orchestrate across mesh-networked nodes.",
   "license": "MIT",
   "author": "Aaron Scherer <me@aaronscherer.me>",