ccstatusline 2.0.13 → 2.0.14

package/README.md

@@ -34,7 +34,9 @@
 - [Recent Updates](#-recent-updates)
 - [Features](#-features)
 - [Quick Start](#-quick-start)
+- [Windows Support](#-windows-support)
 - [Usage](#-usage)
+- [API Documentation](#-api-documentation)
 - [Development](#️-development)
 - [Contributing](#-contributing)
 - [License](#-license)
@@ -44,6 +46,10 @@
 
 ## 🆕 Recent Updates
 
+### v2.0.14 - Add remaining mode toggle to Context Percentage widgets
+
+- **Remaining Mode** - You can now toggle the Context Percentage widgets between usage percentage and remaining percentage when configuring them in the TUI by pressing the 'l' key.
+
 ### v2.0.12 - Custom Text widget now supports emojis
 
 - **👾 Emoji Support** - You can now paste emoji into the custom text widget. You can also turn on the merge option to get emoji labels for your widgets like this:
@@ -145,6 +151,176 @@ The interactive configuration tool provides a terminal UI where you can:
 
 ---
 
+## 🪟 Windows Support
+
+ccstatusline works seamlessly on Windows with full feature compatibility across PowerShell (5.1+ and 7+), Command Prompt, and Windows Subsystem for Linux (WSL).
+
+### Installation on Windows
+
+#### Option 1: Using Bun (Recommended)
+```powershell
+# Install Bun for Windows
+irm bun.sh/install.ps1 | iex
+
+# Run ccstatusline
+bunx ccstatusline@latest
+```
+
+#### Option 2: Using Node.js
+```powershell
+# Using npm
+npx ccstatusline@latest
+
+# Or with Yarn
+yarn dlx ccstatusline@latest
+
+# Or with pnpm
+pnpm dlx ccstatusline@latest
+```
+
+### Windows-Specific Features
+
+#### Powerline Font Support
+For optimal Powerline rendering on Windows:
+
+**Windows Terminal** (Recommended):
+- Supports Powerline fonts natively
+- Download from [Microsoft Store](https://aka.ms/terminal)
+- Auto-detects compatible fonts
+
+**PowerShell/Command Prompt**:
+```powershell
+# Install JetBrains Mono Nerd Font via winget
+winget install DEVCOM.JetBrainsMonoNerdFont
+
+# Alternative: Install base JetBrains Mono font
+winget install "JetBrains.JetBrainsMono"
+
+# Or download manually from: https://www.nerdfonts.com/font-downloads
+```
+
+#### Path Handling
+ccstatusline automatically handles Windows-specific paths:
+- Git repositories work with both `/` and `\` path separators
+- Current Working Directory widget displays Windows-style paths correctly
+- Full support for mapped network drives and UNC paths
+- Handles Windows drive letters (C:, D:, etc.)
+
+### Windows Troubleshooting
+
+#### Common Issues & Solutions
+
+**Issue**: Powerline symbols showing as question marks or boxes
+```powershell
+# Solution: Install a compatible Nerd Font
+winget install JetBrainsMono.NerdFont
+# Then set the font in your terminal settings
+```
+
+**Issue**: Git commands not recognized
+```powershell
+# Check if Git is installed and in PATH
+git --version
+
+# If not found, install Git:
+winget install Git.Git
+# Or download from: https://git-scm.com/download/win
+```
+
+**Issue**: Permission errors during installation
+```powershell
+# Use non-global installation (recommended)
+npx ccstatusline@latest
+
+# Or run PowerShell as Administrator for global install
+```
+
+**Issue**: "Execution Policy" errors in PowerShell
+```powershell
+# Temporarily allow script execution
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Issue**: Windows Defender blocking execution
+```powershell
+# If Windows Defender flags the binary:
+# 1. Open Windows Security
+# 2. Go to "Virus & threat protection"
+# 3. Add exclusion for the ccstatusline binary location
+# Or use temporary bypass (not recommended for production):
+Add-MpPreference -ExclusionPath "$env:USERPROFILE\.bun\bin"
+```
+
+#### Windows Subsystem for Linux (WSL)
+ccstatusline works perfectly in WSL environments:
+
+```bash
+# Install in WSL Ubuntu/Debian
+curl -fsSL https://bun.sh/install | bash
+source ~/.bashrc
+bunx ccstatusline@latest
+```
+
+**WSL Benefits**:
+- Native Unix-style path handling
+- Better font rendering in WSL terminals
+- Seamless integration with Linux development workflows
+
+### Windows Terminal Configuration
+
+For the best experience, configure Windows Terminal with these recommended settings:
+
+#### Terminal Settings (settings.json)
+```json
+{
+  "profiles": {
+    "defaults": {
+      "font": {
+        "face": "JetBrainsMono Nerd Font",
+        "size": 12
+      },
+      "colorScheme": "One Half Dark"
+    }
+  }
+}
+```
+
+#### Claude Code Integration
+Configure ccstatusline in your Claude Code settings:
+
+**For Bun users** (Windows: `%USERPROFILE%\.claude\settings.json`):
+```json
+{
+  "statusLine": "bunx ccstatusline@latest"
+}
+```
+
+**For npm users**:
+```json
+{
+  "statusLine": "npx ccstatusline@latest"
+}
+```
+
+### Performance on Windows
+
+ccstatusline is optimized for Windows performance:
+- **Bun runtime**: Significantly faster startup times on Windows
+- **Caching**: Intelligent caching of git status and file operations
+- **Async operations**: Non-blocking command execution
+- **Memory efficient**: Minimal resource usage
+
+### Windows-Specific Widget Behavior
+
+Some widgets have Windows-specific optimizations:
+
+- **Current Working Directory**: Displays Windows drive letters and UNC paths
+- **Git Widgets**: Handle Windows line endings (CRLF) automatically  
+- **Custom Commands**: Support both PowerShell and cmd.exe commands
+- **Block Timer**: Accounts for Windows timezone handling
+
+---
+
 ## 📖 Usage
 
 Once configured, ccstatusline automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions.
@@ -291,6 +467,38 @@ When terminal width is detected, status lines automatically truncate with ellips
 
 ---
 
+## 📖 API Documentation
+
+Complete API documentation is generated using TypeDoc and includes detailed information about:
+
+- **Core Types**: Configuration interfaces, widget definitions, and render contexts
+- **Widget System**: All available widgets and their customization options  
+- **Utility Functions**: Helper functions for rendering, configuration, and terminal handling
+- **Status Line Rendering**: Core rendering engine and formatting options
+
+### Generating Documentation
+
+To generate the API documentation locally:
+
+```bash
+# Generate documentation
+bun run docs
+
+# Clean generated documentation
+bun run docs:clean
+```
+
+The documentation will be generated in the `docs/` directory and can be viewed by opening `docs/index.html` in your web browser.
+
+### Documentation Structure
+
+- **Types**: Core TypeScript interfaces and type definitions
+- **Widgets**: Individual widget implementations and their APIs
+- **Utils**: Utility functions for configuration, rendering, and terminal operations
+- **Main Module**: Primary entry point and orchestration functions
+
+---
+
 ## 🛠️ Development
 
 ### Prerequisites

package/dist/ccstatusline.js

@@ -51374,7 +51374,7 @@ import { execSync as execSync3 } from "child_process";
 import * as fs5 from "fs";
 import * as path4 from "path";
 var __dirname = "/Users/sirmalloc/Projects/Personal/ccstatusline/src/utils";
-var PACKAGE_VERSION = "2.0.13";
+var PACKAGE_VERSION = "2.0.14";
 function getPackageVersion() {
   if (/^\d+\.\d+\.\d+/.test(PACKAGE_VERSION)) {
     return PACKAGE_VERSION;
@@ -53308,23 +53308,52 @@ class ContextPercentageWidget {
     return "blue";
   }
   getDescription() {
-    return "Shows percentage of context window used (of 200k tokens)";
+    return "Shows percentage of context window used or remaining (of 200k tokens)";
   }
   getDisplayName() {
     return "Context %";
   }
   getEditorDisplay(item) {
-    return { displayText: this.getDisplayName() };
+    const isInverse = item.metadata?.inverse === "true";
+    const modifiers = [];
+    if (isInverse) {
+      modifiers.push("remaining");
+    }
+    return {
+      displayText: this.getDisplayName(),
+      modifierText: modifiers.length > 0 ? `(${modifiers.join(", ")})` : undefined
+    };
+  }
+  handleEditorAction(action, item) {
+    if (action === "toggle-inverse") {
+      const currentState = item.metadata?.inverse === "true";
+      return {
+        ...item,
+        metadata: {
+          ...item.metadata,
+          inverse: (!currentState).toString()
+        }
+      };
+    }
+    return null;
   }
   render(item, context, settings) {
+    const isInverse = item.metadata?.inverse === "true";
     if (context.isPreview) {
-      return item.rawValue ? "9.3%" : "Ctx: 9.3%";
+      const previewValue = isInverse ? "90.7%" : "9.3%";
+      return item.rawValue ? previewValue : `Ctx: ${previewValue}`;
     } else if (context.tokenMetrics) {
-      const percentage = Math.min(100, context.tokenMetrics.contextLength / 200000 * 100);
-      return item.rawValue ? `${percentage.toFixed(1)}%` : `Ctx: ${percentage.toFixed(1)}%`;
+      const usedPercentage = Math.min(100, context.tokenMetrics.contextLength / 200000 * 100);
+      const displayPercentage = isInverse ? 100 - usedPercentage : usedPercentage;
+      return item.rawValue ? `${displayPercentage.toFixed(1)}%` : `Ctx: ${displayPercentage.toFixed(1)}%`;
     }
     return null;
   }
+  getCustomKeybinds() {
+    return [
+      { key: "l", label: "(l)eft/remaining", action: "toggle-inverse" }
+    ];
+  }
   supportsRawValue() {
     return true;
   }
@@ -53338,23 +53367,52 @@ class ContextPercentageUsableWidget {
     return "green";
   }
   getDescription() {
-    return "Shows percentage of usable context window used (of 160k tokens before auto-compact)";
+    return "Shows percentage of usable context window used or remaining (of 160k tokens before auto-compact)";
   }
   getDisplayName() {
     return "Context % (usable)";
   }
   getEditorDisplay(item) {
-    return { displayText: this.getDisplayName() };
+    const isInverse = item.metadata?.inverse === "true";
+    const modifiers = [];
+    if (isInverse) {
+      modifiers.push("remaining");
+    }
+    return {
+      displayText: this.getDisplayName(),
+      modifierText: modifiers.length > 0 ? `(${modifiers.join(", ")})` : undefined
+    };
+  }
+  handleEditorAction(action, item) {
+    if (action === "toggle-inverse") {
+      const currentState = item.metadata?.inverse === "true";
+      return {
+        ...item,
+        metadata: {
+          ...item.metadata,
+          inverse: (!currentState).toString()
+        }
+      };
+    }
+    return null;
   }
   render(item, context, settings) {
+    const isInverse = item.metadata?.inverse === "true";
     if (context.isPreview) {
-      return item.rawValue ? "11.6%" : "Ctx(u): 11.6%";
+      const previewValue = isInverse ? "88.4%" : "11.6%";
+      return item.rawValue ? previewValue : `Ctx(u): ${previewValue}`;
     } else if (context.tokenMetrics) {
-      const percentage = Math.min(100, context.tokenMetrics.contextLength / 160000 * 100);
-      return item.rawValue ? `${percentage.toFixed(1)}%` : `Ctx(u): ${percentage.toFixed(1)}%`;
+      const usedPercentage = Math.min(100, context.tokenMetrics.contextLength / 160000 * 100);
+      const displayPercentage = isInverse ? 100 - usedPercentage : usedPercentage;
+      return item.rawValue ? `${displayPercentage.toFixed(1)}%` : `Ctx(u): ${displayPercentage.toFixed(1)}%`;
     }
     return null;
   }
+  getCustomKeybinds() {
+    return [
+      { key: "l", label: "(l)eft/remaining", action: "toggle-inverse" }
+    ];
+  }
   supportsRawValue() {
     return true;
   }
@@ -53379,10 +53437,9 @@ class SessionClockWidget {
   render(item, context, settings) {
     if (context.isPreview) {
       return item.rawValue ? "2hr 15m" : "Session: 2hr 15m";
-    } else if (context.sessionDuration) {
-      return item.rawValue ? context.sessionDuration : `Session: ${context.sessionDuration}`;
     }
-    return null;
+    const duration3 = context.sessionDuration ?? "0m";
+    return item.rawValue ? duration3 : `Session: ${duration3}`;
   }
   supportsRawValue() {
     return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccstatusline",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "description": "A customizable status line formatter for Claude Code CLI",
   "module": "src/ccstatusline.ts",
   "type": "module",
@@ -17,12 +17,15 @@
     "example": "cat scripts/payload.example.json | bun start",
     "prepublishOnly": "bun run build",
     "lint": "bun tsc --noEmit; eslint . --config eslint.config.js --max-warnings=999999 --fix",
-    "test": "bun vitest"
+    "test": "bun vitest",
+    "docs": "typedoc",
+    "docs:clean": "rm -rf docs"
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
     "@stylistic/eslint-plugin": "^5.2.3",
     "@types/bun": "latest",
+    "@types/pluralize": "^0.0.33",
     "@types/react": "^19.1.10",
     "chalk": "^5.5.0",
     "eslint": "^9.33.0",
@@ -34,16 +37,16 @@
     "ink": "^6.2.0",
     "ink-gradient": "^3.0.0",
     "ink-select-input": "^6.2.0",
+    "pluralize": "^8.0.0",
     "react": "^19.1.1",
     "react-devtools-core": "^6.1.5",
     "strip-ansi": "^7.1.0",
     "tinyglobby": "^0.2.14",
+    "typedoc": "^0.28.12",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.39.1",
     "vitest": "^3.2.4",
-    "zod": "^4.0.17",
-    "pluralize": "^8.0.0",
-    "@types/pluralize": "^0.0.33"
+    "zod": "^4.0.17"
   },
   "keywords": [
     "claude",