encode

type File struct {
	Name string
	Data []byte
}

type Format string

type Frame struct {
	Data []byte    `json:"data"`
	TS   time.Time `json:"ts"`

	// CSSWidth/CSSHeight are the frame's size in page CSS pixels. They exist so
	// a Mark's page coordinates map onto image pixels when the capture was
	// scaled down. Zero means "the image's own pixel dimensions", i.e. 1:1.
	CSSWidth  float64 `json:"css_width,omitempty"`
	CSSHeight float64 `json:"css_height,omitempty"`

	// Marks are the actions that landed while this frame was on screen. They are
	// carried, not drawn: Options.Annotate decides at export whether they become
	// pixels.
	Marks []Mark `json:"marks,omitempty"`
}

type HAROpts struct {
	Version string
	Now     time.Time
}

type Label struct {
	N    int
	X, Y float64
}

type Mark struct {
	X       float64 `json:"x"`
	Y       float64 `json:"y"`
	Command string  `json:"command,omitempty"`
}

type NetEntry struct {
	ID           string  `json:"id"`
	Method       string  `json:"method"`
	URL          string  `json:"url"`
	Type         string  `json:"type"`
	Status       *int64  `json:"status"` // nil: no status (pending or network-level failure)
	StatusText   string  `json:"status_text"`
	StartedAt    string  `json:"started_at"` // RFC 3339 UTC, ms; "" when the row carries none
	StartedMs    int64   `json:"started_ms"`
	DurationMs   *int64  `json:"duration_ms"` // nil: not finished
	RequestSize  int64   `json:"request_size"`
	ResponseSize int64   `json:"response_size"`
	FromCache    bool    `json:"from_cache"`
	Failed       bool    `json:"failed"`
	Error        *string `json:"error"`
	Pending      bool    `json:"pending"`

	RequestHeaders         map[string]string `json:"request_headers"`
	ResponseHeaders        map[string]string `json:"response_headers"`
	RequestBody            *string           `json:"request_body"`
	RequestBodyUnavailable bool              `json:"request_body_unavailable"`
	ResponseBody           *string           `json:"response_body"`
	BodyUnavailable        bool              `json:"body_unavailable"`
	BodyTruncated          bool              `json:"body_truncated"`
}

type Options struct {
	Format Format

	// FPS is the playback cadence used when the frames carry no usable
	// timestamps, and the floor/ceiling is applied to timestamp-derived delays
	// either way.
	FPS float64

	// Loop is the GIF loop count: 0 loops forever, n > 0 plays n times.
	Loop int

	// Annotate composites the position markers. Off by default — a README asset
	// must not carry the tool's own drawing (US-5).
	Annotate bool

	// MaxBytes is a best-effort size ceiling. See reduce(): the export is
	// re-encoded at reduced scale (and then a reduced frame count) until it
	// fits, and the values actually used are reported in Result.
	MaxBytes int
}

type Result struct {
	Data  []byte // gif/mp4/webm bytes (nil for FormatFrames)
	Files []File // FormatFrames only

	Format     Format
	Frames     int
	FPS        float64
	Scale      float64 // 1 unless --max-size forced a reduction
	Width      int
	Height     int
	Bytes      int
	DurationMs int64
	Annotated  bool
	Reduced    bool // --max-size changed the scale and/or the frame count

	// DecodeFailures counts captured frames that did not decode as an image and
	// were therefore left out. They are reported rather than fatal: see
	// decodeAll.
	DecodeFailures int

	// WithinMaxSize reports whether the ceiling was actually met. False means
	// the reduction ladder bottomed out first — a best-effort bound, reported
	// rather than silently missed.
	WithinMaxSize bool

	// ReductionTimedOut reports that the --max-size ladder was cut short by the
	// context rather than by its own bounds, so this is the best COMPLETE
	// attempt and not the best attempt available.
	ReductionTimedOut bool
}