Scaffold C++20 screencast project with Meson, agent workflow, and phase plan

include/screencast/capture/capture.h

@@ -0,0 +1,56 @@
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <optional>
+#include <span>
+#include <string_view>
+#include <variant>
+#include <vector>
+
+namespace sc {
+
+// Opaque resource owned by the capture implementation.
+struct CapturedFrame {
+    int width = 0;
+    int height = 0;
+    uint64_t timestamp_ns = 0; // capture clock, monotonic
+    std::vector<std::byte> pixels;
+    // TODO: pixel format, stride, FD handle for dmabuf
+};
+
+// Capture target: whole monitor, specific window, or a region.
+struct CaptureTargetWholeScreen {};
+struct CaptureTargetWindow {
+    std::string_view window_id;
+};
+struct CaptureTargetRegion {
+    int x = 0;
+    int y = 0;
+    int width = 0;
+    int height = 0;
+};
+
+using CaptureTarget = std::variant<
+    CaptureTargetWholeScreen,
+    CaptureTargetWindow,
+    CaptureTargetRegion>;
+
+class CaptureSession {
+public:
+    virtual ~CaptureSession() = default;
+
+    // Blocking call to acquire one frame. Returns std::nullopt on graceful stop.
+    virtual std::optional<CapturedFrame> next_frame() = 0;
+
+    // Request the session to stop. May be called from another thread.
+    virtual void stop() = 0;
+};
+
+// Factory for the PipeWire / xdg-desktop-portal capture backend.
+class CaptureFactory {
+public:
+    static std::unique_ptr<CaptureSession> create(CaptureTarget target);
+};
+
+} // namespace sc