api

type GenerationOutput struct {
	Results      []GenerationResult
	OutputFolder string
	Elapsed      time.Duration

	// MetadataSkipped is true when Metadata was requested but a saved image wasn't PNG, so nothing was embedded.
	MetadataSkipped bool
}

type GenerationResult struct {
	Index     int
	ImageData []byte
	Filename  string
	Error     error
	Duration  time.Duration // wall time of the provider call that produced this image
	// contains filtered or unexported fields
}

type Params struct {
	OutputFolder     string
	OutputFilename   string // -f
	NumImages        int    // total, across all batches
	PreserveFilename bool   // -r
	RefInputPath     string // original -i path, used by -r

	// MaxParallel caps in-flight provider calls within this run. 0
	// (default) means unlimited — every batch fires immediately, the
	// pre-existing behaviour. Ignored when Sem is non-nil.
	MaxParallel int

	// Sem, when non-nil, is a shared concurrency semaphore — the batch
	// runner creates one and passes the same channel into every entry's
	// orchestrator call so a single --max-parallel cap covers both the
	// per-entry and per-image axes. Single-shot leaves this nil and the
	// orchestrator builds a private sem from MaxParallel.
	Sem chan struct{}

	// Progress, when non-nil, receives each result in completion order and is closed when the run finishes.
	// Sends are synchronous: it MUST be buffered to >= NumImages or drained concurrently, else RunGeneration blocks.
	Progress chan<- GenerationResult

	// Metadata, when non-empty, is embedded into PNG output (--embed-metadata); a no-op for other formats.
	Metadata []images.TextTag
}