CLI flag to skip post-capture clear during capture runs

[ewilderj]

Description

Add an optional CLI flag to skip the automatic display clear that happens after each capture run, useful for debugging and batch capture scenarios.

Work Required

1. Add CLI Flag: Add --no-clear or --skip-clear flag to capture commands
2. Modify Capture Logic: Update capture/capture.js to conditionally skip clear
3. Update Help Text: Document new flag in CLI help and README
4. Test Functionality: Verify flag works correctly without side effects

Implementation Details

Based on capture/capture.js, the current behavior:

Current Clear Process

// In captureTemplate() finally block
try {
  await this.clearDisplay(null);
} catch (e) {
  this.debug(`Post-capture clear failed: ${e.message}`);
}

The clearDisplay() method:

• Uses CLI to call hdisplay clear
• Waits ~1200ms for frontend crossfade cleanup
• Ensures clean state for next capture

Proposed Changes

Add flag to both capture commands:

• hdisplay capture:all --no-clear
• hdisplay capture:template <id> --no-clear

Pass flag to BlackBoxCapture constructor and conditionally skip clear.

Use Cases

When to Skip Clear

• Debugging: Leave content visible for inspection
• Batch Operations: Running multiple captures in sequence
• Development: Iterating on capture profiles
• Performance: Avoiding clear delay when not needed

When to Keep Clear (Default)

• Gallery Generation: Ensure clean captures
• Production Runs: Consistent starting state
• Automated Testing: Reliable capture environment

Files to Modify

• cli/index.mjs - Add --no-clear flag to capture commands
• capture/capture.js - Add conditional clear logic to captureTemplate()

Implementation Approach

CLI Changes

.option('--no-clear', 'Skip post-capture display clear')

Capture Changes

constructor(options = {}) {
  // ...
  this.skipClear = options.skipClear || false;
}

// In captureTemplate() finally block
if (!this.skipClear) {
  try {
    await this.clearDisplay(null);
  } catch (e) {
    this.debug(`Post-capture clear failed: ${e.message}`);
  }
}

Testing

• Test capture:all --no-clear leaves final template visible
• Test capture:template <id> --no-clear leaves template visible
• Test default behavior (clear after capture) still works
• Verify no impact on capture quality or timing

Acceptance Criteria

• CLI flag is properly documented in help text
• Clear is skipped when flag is provided
• Default behavior (clear after capture) is preserved when flag not used
• No impact on capture functionality when flag is used
• Flag works for both capture:all and capture:template commands