Color chosen for windows and vscode result in poor contrast for readability

[rexsilex]

There needs to be proper contrast between text and background. Maybe even a choice for dark color schemes? Or a minimal saturation to support white terminal fonts.

[acreeger]

Bug Report Analysis

Problem Summary
Terminal text colors in the loom overlay have poor contrast, making them difficult to read.

User Impact
Users with specific terminal color schemes experience readability issues when viewing loom overlay content.

Expected Behavior
Terminal text in the loom overlay should have sufficient contrast for readability regardless of the user's terminal color scheme.

Actual Behavior
Terminal text colors result in poor contrast, making content difficult to read.

Next Steps

• Technical analysis to identify how to detect terminal text color at loom creation time
• Implementation planning for automatic color scheme selection based on detected terminal colors
• Execution and testing with various terminal color schemes

---

📋 Complete Context & Details (click to expand)

Reproduction Steps

1. Use a terminal with specific color scheme settings (details to be determined during technical analysis)
2. Create a loom overlay using il start <issue-number>
3. Observe the terminal text in the loom overlay
4. Notice poor contrast between text and background

Additional Context

• Issue specifically affects terminal text colors, not VS Code status bar or activity bar
• User prefers automatic detection: Detect terminal text color at loom creation time and choose an appropriate color scheme accordingly
• Solution should work across different terminal color schemes without manual user intervention
• Frequency/consistency: Appears to affect specific terminal color configurations

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 2-3
• Estimated lines of code: 150-200
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good (color utilities already well-architected, TerminalColorManager <200 LOC)
• Overall risk level: Low

Reasoning: The codebase already has well-structured color infrastructure in place (color.ts, TerminalColorManager, VSCodeIntegration). The task is to add terminal text color detection and adjust the selection logic - a focused enhancement that will primarily modify TerminalColorManager with new detection methods and potentially enhance the color selection logic in color.ts. No breaking changes, cross-cutting updates, or large file modifications required.

[acreeger]

Combined Analysis & Plan - Issue #373

Executive Summary

Terminal text colors have poor contrast when loom workspace uses light pastel background colors (RGB 220-255) while the user has a dark terminal theme with light text. The solution is to detect macOS dark/light mode at loom creation time and select an appropriate color palette - light pastels for light mode (dark text), darker saturated colors for dark mode (light text).

HIGH/CRITICAL Risks

• Terminal I/O complexity: OSC 10/11 escape sequence approach requires raw terminal mode and may not work in all terminals - recommending simpler macOS API approach instead.

Implementation Overview

High-Level Execution Phases

1. Add dark mode detection: Create detectDarkMode() function using AppleScript on macOS
2. Create dark mode palette: Add new color palette with darker, more saturated colors for dark terminals
3. Integrate detection at color selection: Call detection before palette selection in LoomManager
4. Update terminal color application: Pass theme mode through to color selection logic

Quick Stats

• 3 files to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Light pastel background colors (RGB 220-255) result in poor contrast with light terminal text on dark backgrounds
• Architectural context: Colors are generated in color.ts, applied via terminal.ts AppleScript, and orchestrated by LoomLauncher.ts
• Edge cases: User may have custom terminal themes, or may switch themes mid-session; detection happens once at loom creation time

Third-Party Research

Approach 1: Terminal Text Color Detection (OSC 10/11)

• OSC 10 queries foreground color, OSC 11 queries background color using escape sequences
• Format: Send \x1b]10;?\x1b\\ and parse response rgb:RRRR/GGGG/BBBB
• Requires raw terminal mode, blocking stdin read, and timeout handling
• Many terminals (Tabby, some iTerm2 configs) respond incorrectly or not at all
• Source: Knowledge Bits - Terminal FG/BG Colors

Approach 2: macOS Dark Mode Detection (Recommended)

• macOS provides system-level dark/light mode detection
• Can query via AppleScript: tell application "System Events" to tell appearance preferences to get dark mode
• Works reliably on all macOS versions supporting dark mode (Mojave+)
• The COLORFGBG environment variable is NOT set by Terminal.app
• Source: sindresorhus/dark-mode, arslan.io dark mode article

Codebase Research

• Entry point: /src/utils/color.ts:29-48 - getColorPalette() returns 16 light pastel colors
• Dependencies: selectDistinctColor() in color.ts used by LoomManager.ts:262, color passed to LoomLauncher.ts
• Similar patterns: Already uses AppleScript for terminal operations in /src/utils/terminal.ts:59-75
• Historical: Palette was intentionally made subtle/pastel for professional appearance with dark text

Affected Files

• /src/utils/color.ts:29-48 - Add dark mode palette alongside existing light palette
• /src/utils/color.ts:163-218 - Modify selectDistinctColor() to accept theme mode parameter
• /src/utils/terminal.ts:19-25 - Add detectDarkMode() function using AppleScript
• /src/lib/LoomManager.ts:254-263 - Call dark mode detection before color selection

Integration Points

• selectDistinctColor() called from LoomManager.createIloom() (line 262)
• Color passed through LaunchLoomOptions.colorHex to LoomLauncher
• Terminal color applied via AppleScript in terminal.ts (lines 130-134, 173-176)

Medium Severity Risks

• Detection timing: Dark mode detection happens at loom creation; if user switches theme afterward, color won't update (acceptable - matches current behavior)
• Non-macOS platforms: Detection returns "light" as default on Linux/Windows where terminal colors aren't applied anyway

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/utils/color.test.ts (MODIFY)

Click to expand complete test structure (12 lines)

describe('getDarkColorPalette', () => {
  it('returns 16 distinct darker colors for dark mode')
  it('all colors have RGB values in appropriate dark range (80-180)')
  it('maintains minimum color distance between all pairs')
})

describe('selectDistinctColor with theme mode', () => {
  it('uses light palette when themeMode is "light"')
  it('uses dark palette when themeMode is "dark"')
  it('defaults to light palette when themeMode is undefined')
})

Test File: /src/utils/terminal.test.ts (MODIFY)

describe('detectDarkMode', () => {
  it('returns "dark" when AppleScript indicates dark mode')
  it('returns "light" when AppleScript indicates light mode')
  it('returns "light" on non-macOS platforms')
})

Files to Modify

1. /src/utils/terminal.ts:19-25

Change: Add detectDarkMode() function using AppleScript
Cross-cutting impact: New export consumed by LoomManager

// After detectPlatform() function, add:
export type ThemeMode = 'light' | 'dark'

export async function detectDarkMode(): Promise<ThemeMode> {
  // Use AppleScript to query macOS appearance
  // Returns 'light' as default for non-macOS
}

2. /src/utils/color.ts:29-48

Change: Add getDarkColorPalette() function with darker, more saturated colors

// After getColorPalette(), add new function
export function getDarkColorPalette(): RgbColor[] {
  // 16 darker colors with RGB values ~80-180 for good contrast with light text
}

3. /src/utils/color.ts:163-218

Change: Modify selectDistinctColor() signature to accept optional theme mode parameter

// Update function signature:
export function selectDistinctColor(
  branchName: string, 
  usedHexColors: string[],
  themeMode: ThemeMode = 'light'  // new optional parameter
): ColorData {
  // Use getColorPalette() or getDarkColorPalette() based on themeMode
}

4. /src/lib/LoomManager.ts:254-263

Change: Call detectDarkMode() before color selection

// Before line 262 (selectDistinctColor call):
const { detectDarkMode } = await import('../utils/terminal.js')
const themeMode = await detectDarkMode()

// Update line 262:
const colorData = selectDistinctColor(branchName, usedHexColors, themeMode)

Detailed Execution Order

Phase 1: Add Dark Mode Detection

1. Add ThemeMode type export to /src/utils/terminal.ts:25 -> Verify: TypeScript compiles
2. Add detectDarkMode() function to /src/utils/terminal.ts:26-45 -> Verify: Function exported
3. Add tests for detectDarkMode() in /src/utils/terminal.test.ts -> Verify: Tests pass

Phase 2: Add Dark Mode Palette

1. Add getDarkColorPalette() to /src/utils/color.ts:49-68 -> Verify: Returns 16 RgbColor entries
2. Add tests for dark palette in /src/utils/color.test.ts -> Verify: Tests pass
3. Run pnpm build -> Verify: TypeScript compiles

Phase 3: Integrate Theme Mode in Color Selection

1. Modify selectDistinctColor() signature in /src/utils/color.ts:163 -> Verify: New parameter accepted
2. Update palette selection logic in selectDistinctColor() -> Verify: Correct palette used
3. Update tests for theme mode in /src/utils/color.test.ts -> Verify: Tests pass

Phase 4: Wire Up Detection in LoomManager

1. Import detectDarkMode in /src/lib/LoomManager.ts -> Verify: Import resolves
2. Call detection before color selection at line 262 -> Verify: Theme mode passed
3. Run pnpm build && pnpm test -> Verify: All tests pass

Dependencies and Configuration

None required.

[acreeger]

Implementation In Progress

Continuing implementation of dark mode detection for improved color contrast.

Tasks

• Add detectDarkMode() function to terminal.ts
• Add getDarkColorPalette() function to color.ts
• Modify selectDistinctColor() to accept themeMode parameter
• Wire up dark mode detection in LoomManager.ts
• Add tests for detectDarkMode()
• Add tests for getDarkColorPalette() and selectDistinctColor() with themeMode
• Run validation (typecheck, tests, lint)

Current: Wiring up dark mode detection in LoomManager.ts
ETA: ~10 minutes

[acreeger]

Implementation Complete

Summary

Implemented macOS dark mode detection to automatically select appropriate workspace colors based on the user's system theme. When dark mode is enabled, iloom now uses darker, more saturated colors that provide good contrast with light terminal text.

Changes Made

New Functions

src/utils/terminal.ts

• Added ThemeMode type ('light' | 'dark')
• Added detectDarkMode() function using AppleScript to query macOS appearance preferences
• Returns 'light' as default on non-macOS platforms or detection failures

src/utils/color.ts

• Added getDarkColorPalette() returning 16 darker colors (RGB ~80-180 range) optimized for dark terminal themes
• Updated selectDistinctColor() to accept optional themeMode parameter
• Updated generateColorFromBranchName() to accept optional themeMode parameter

Integration

src/lib/LoomManager.ts

• createIloom() now detects dark mode before selecting workspace color (line 262-266)
• launchLoom() also uses theme-aware color generation for existing branches (line 1053-1057)

Color Palettes

Mode	RGB Range	Example Colors
Light (existing)	220-255	Soft pastels - good with dark text
Dark (new)	80-180	Deeper tones - good with light text

Test Coverage

• Added 3 new test cases for detectDarkMode() in terminal.test.ts
• Added 6 new test cases for getDarkColorPalette() and theme-aware selection in color.test.ts

Validation

• ✅ pnpm build - Success
• ✅ pnpm test - All 3034 tests pass
• ✅ pnpm typecheck - No errors
• ✅ pnpm lint - No errors

[acreeger]

iloom Session Summary

Key Themes:

• Implemented dark mode detection and adaptive color palettes for terminal and VSCode workspace colors to improve readability
• Switched from AppleScript to defaults read command to avoid System Events permission dialogs
• Extended dark mode support to logger colors for better terminal output contrast
• Conducted comprehensive code review identifying and fixing dynamic import violations

---

Session Details (click to expand)

Key Insights

• Terminal color contrast issues stem from using light pastel colors (RGB 220-255) with dark terminal themes that have light text
• The same color selection logic affects both VSCode title bar colors and terminal background colors, ensuring consistency
• Dark mode detection requires permission-free approaches - defaults read -g AppleInterfaceStyle works without dialogs while AppleScript requires System Events permission
• Logger module initialization triggers dark mode detection on load, requiring careful consideration of permission requests

Decisions Made

• Dark palette RGB range (25-85): Chose darker, muted colors for dark mode vs original light pastels (220-255) to provide adequate contrast with light terminal text
• Minimum color distance (10 vs 20): Accepted lower minimum distance for dark palette (10) vs collision threshold (20), with graceful fallback to hash-based colors when needed
• Detection method (defaults vs AppleScript): Switched to defaults read -g AppleInterfaceStyle to avoid permission dialogs that would interrupt user experience
• Static imports over dynamic: Replaced dynamic imports of detectDarkMode with static import to comply with CLAUDE.md guidelines and improve performance
• Logger color mapping: Used brighter variants (cyan, greenBright, yellowBright, redBright) in dark mode vs standard colors in light mode

Challenges Resolved

• System Events permission dialog: Initially used AppleScript which triggered permission request on module load - resolved by switching to defaults read command
• Color brightness tuning: First iteration (RGB 30-70) produced colors too similar (min distance 5) - adjusted to 25-85 range with better variation to meet minimum distance requirement of 10
• Stored colors not updating: Existing looms retain their original stored colors - users need to create new looms or cleanup old ones to see dark mode colors
• Code review findings: Identified and fixed dynamic import violations that added complexity and hurt performance

Lessons Learned

• Permission-free alternatives should be preferred for background operations - defaults read vs AppleScript is a good example
• Color palette design requires balancing distinctness (minimum distance) with aesthetics (muted vs bright)
• When implementing theme detection, consider both initial load and stored state scenarios
• CLAUDE.md guidelines on dynamic imports exist for good reasons - static imports improve performance and code clarity
• Testing color changes requires creating fresh looms since stored colors persist from creation time

---

Generated with 🤖❤️ by iloom.ai