ccstatusline 2.0.12 → 2.0.14

package/LICENSE

@@ -18,8 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-Original author: Matthew Breedlove (https://github.com/sirmalloc)
-Official repository: https://github.com/sirmalloc/ccstatusline
+SOFTWARE.

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.12";
+var PACKAGE_VERSION = "2.0.14";
 function getPackageVersion() {
   if (/^\d+\.\d+\.\d+/.test(PACKAGE_VERSION)) {
     return PACKAGE_VERSION;
@@ -52934,7 +52934,17 @@ function renderStatusLine(widgets, settings, context, preRenderedWidgets, preCal
     if (!widget)
       continue;
     if (widget.type === "separator") {
-      if (i > 0 && !preRenderedWidgets[i - 1]?.content)
+      let hasContentBefore = false;
+      for (let j = i - 1;j >= 0; j--) {
+        const prevWidget = widgets[j];
+        if (prevWidget && prevWidget.type !== "separator" && prevWidget.type !== "flex-separator") {
+          if (preRenderedWidgets[j]?.content) {
+            hasContentBefore = true;
+            break;
+          }
+        }
+      }
+      if (!hasContentBefore)
         continue;
       const sepChar = widget.character ?? (settings.defaultSeparator ?? "|");
       const formattedSep = formatSeparator(sepChar);
@@ -53298,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;
   }
@@ -53328,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;
   }
@@ -53369,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;
@@ -54034,11 +54101,13 @@ class CurrentWorkingDirWidget {
     const segments = item.metadata?.segments ? parseInt(item.metadata.segments, 10) : undefined;
     let displayPath = cwd2;
     if (segments && segments > 0) {
-      const pathParts = cwd2.split("/");
+      const useBackslash = cwd2.includes("\\") && !cwd2.includes("/");
+      const outSep = useBackslash ? "\\" : "/";
+      const pathParts = cwd2.split(/[\\/]+/);
       const filteredParts = pathParts.filter((part) => part !== "");
       if (filteredParts.length > segments) {
         const selectedSegments = filteredParts.slice(-segments);
-        displayPath = ".../" + selectedSegments.join("/");
+        displayPath = "..." + outSep + selectedSegments.join(outSep);
       }
     }
     return item.rawValue ? displayPath : `cwd: ${displayPath}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccstatusline",
-  "version": "2.0.12",
+  "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",