cdp

type CDPConfig struct {
	// SessionID is the identifier of the owning session; used to create
	// per-session temporary directories for wrapper scripts.
	SessionID string
	// ChromePath is the resolved real Chrome binary path (not the wrapper script).
	// When empty, New() returns a noopCDPManager.
	ChromePath string

	// ScreencastQuality is the JPEG compression quality (1–100). Default: 70.
	ScreencastQuality int
	// ScreencastMaxWidth is the maximum frame width in pixels. Default: 1280.
	ScreencastMaxWidth int
	// ScreencastMaxHeight is the maximum frame height in pixels. Default: 800.
	ScreencastMaxHeight int
	// ScreencastMaxFPS is a hint for the frame-rate cap. Default: 15.
	// Currently influences the everyNthFrame parameter sent to Chrome.
	ScreencastMaxFPS int
}

type CDPState struct {
	// Status is the current operational status.
	Status CDPStatus
	// Port is the allocated CDP TCP port on localhost, or 0 if unavailable.
	Port int
}

type CDPStatus int

type CDPStreamManager interface {
	// Allocate reserves a free TCP port and writes Chrome wrapper scripts.
	// Must be called before the tmux session is created so CDP_PORT can be
	// injected into the session environment via ExtraEnv.
	Allocate() error

	// Start begins polling for Chrome on the allocated CDP port and subscribes
	// to screencast frames. Non-blocking: starts a goroutine. Should be called
	// after the tmux session is started so Chrome has already been launched.
	Start(ctx context.Context) error

	// Stop cancels the polling/streaming goroutines, closes the CDP WebSocket,
	// and removes the temporary wrapper-script directory.
	Stop()

	// State returns a snapshot of the current CDP state.
	State() CDPState

	// Port returns the allocated CDP TCP port, or 0 if unavailable.
	Port() int

	// WrapperDir returns the path to the directory containing the Chrome wrapper
	// scripts. Returns "" before Allocate() or when CDP is unavailable.
	WrapperDir() string

	// LatestFrame returns the most recent JPEG frame bytes, or nil if no frame
	// has been received yet.
	LatestFrame() []byte

	// DispatchInput forwards a raw JSON input message from the browser client to
	// Chrome via CDP (e.g. Input.dispatchMouseEvent / Input.dispatchKeyEvent).
	// The message should be a JSON object with "method" and "params" fields.
	DispatchInput(msg []byte) error

	// SetStateChangeCallback registers a callback that is invoked (in a goroutine)
	// each time the CDP state changes. Replaces any previously registered callback.
	SetStateChangeCallback(func(CDPState))

	// ReconcileOrphans removes wrapper-script directories under the cdp-bins path
	// whose session ID does not appear in activeSessionIDs. This cleans up
	// directories left behind by sessions that were deleted without calling Stop().
	ReconcileOrphans(activeSessionIDs []string) error
}

type DepsResult struct {
	// Available is true when a Chrome/Chromium binary was found.
	// Only when Available is true will New() return a live manager.
	Available bool
	// ChromePath is the absolute path to the first Chrome binary found.
	// Empty when Available is false.
	ChromePath string
	// Reason is a human-readable explanation when Available is false.
	Reason string
}