ZQK Screen Capture & Terminal Automation Engine (pkg/screencap)

pkg/screencap provides headless and interactive terminal automation coupled with native screen, window, and rectangular region capture capabilities.

---

1. Capabilities

• Terminal Automation (TerminalAutomator):
• Spawns background CLI sessions with bidirectional pipe control (stdin, stdout, stderr).
• Simulates interactive human typing with millisecond timestamps (TypeCommand, AppendTimelineEvent).
• Records real-time timeline event traces (TimelineEvent) suitable for rendering animated terminal casts and SVG/GIF demos.
• Matches live stdout patterns (WaitForOutput) to synchronize execution phases.
• Visual Capture Engine (Capturer):
• CaptureWindow(ctx, windowID, outputPath): Captures a specific application window by native OS window identifier.
• CaptureRegion(ctx, x, y, width, height, outputPath): Crops and records a designated screen bounding box without capturing full display real-estate.
• CaptureScreen(ctx, outputPath): Full display snapshot.
• MacCapturer: macOS native implementation utilizing headless screencapture -x.

---

2. Architecture & Interfaces

 ┌──────────────────────┐        TypeCommand()         ┌────────────────────┐
 │  TerminalAutomator   ├─────────────────────────────►│    exec.Cmd Pipe   │
 │                      │                              │ (zqk CLI / shell)  │
 │  - Timeline Tracer   │◄─────────────────────────────┤                    │
 │  - Pattern Matcher   │        WaitForOutput()       └────────────────────┘
 └──────────┬───────────┘
            │
            │ Triggers visual snapshot
            ▼
 ┌──────────────────────┐      screencapture -x        ┌────────────────────┐
 │       Capturer       ├─────────────────────────────►│ Artifacts / Images │
 │   (e.g. MacCapturer) │                              │ (.png, timeline)   │
 └──────────────────────┘                              └────────────────────┘

---

3. Usage Example

capturer := screencap.NewMacCapturer()
automator, err := screencap.NewTerminalAutomator(capturer, "bash")
if err != nil {
    log.Fatal(err)
}

if err := automator.Start(); err != nil {
    log.Fatal(err)
}

// Type command and snapshot the terminal window
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
_ = automator.TypeCommand("zqk workflow whats-next")
_ = automator.WaitForOutput(ctx, "Priority Plan")
_ = capturer.CaptureScreen(ctx, "artifacts/whats_next_output.png")

---

4. Operational Role in ZQK

pkg/screencap is used to:

1. Generate deterministic visual evidence for Quality Assurance (VDS Done-Gates and CRIT verification).
2. Automate walkthrough documentation and animated terminal tutorials for community releases.
3. Validate TUI dashboard rendering without manual human intervention.