playlists

type Playlist struct {
	// HoldToken is internal runtime ownership for primary hold-mode playback.
	// It is not part of playlist persistence or API responses.
	HoldToken *tokens.Token
	// AllowedCommands is the bound carried by the script that opened this
	// playlist, and it travels to every item token. A playlist is an
	// indirection like a ZapLink: opening one must not let its items reach
	// commands the script that opened it could not run itself.
	AllowedCommands tokens.CommandPolicy
	ID              string
	// DeckID names the deck on this device the playlist was opened from. It
	// is set only by the deck loader, never from a served playlist, so it is
	// what ties an open playlist to its deck; the ID is whatever its source
	// chose to call it.
	DeckID  string
	Name    string
	Slot    string
	Items   []PlaylistItem
	Index   int
	Playing bool
	// Clear signals the queue handler to remove the active playlist for this slot.
	Clear bool
	// Loop and LoopOne control end-of-playlist behavior set at load time.
	// Loop wraps back to the start; LoopOne repeats the current track.
	Loop    bool
	LoopOne bool
	// ForceRelaunch bypasses playlistNeedsUpdate dedup so the same track can be
	// relaunched for LoopOne and single-item Loop.
	ForceRelaunch bool
	// Refresh replaces the items and name of the active playlist with the
	// same ID in place, keeping its position and playback state and never
	// launching anything. It is ignored when no such playlist is active.
	Refresh bool
	// Unsafe is the playlist's effective trust. It is set either because the
	// items came from a source this device does not trust — a fetched
	// ZapLink, or a cached copy of somebody else's deck — or because the
	// script that opened it was already untrusted, which even the user's own
	// deck inherits. Every item token carries it, so commands that drive
	// input or run programs refuse, the same as the script that opened the
	// playlist.
	Unsafe bool
}

type PlaylistController struct {
	Active     *Playlist
	Background *Playlist
	Current    *Playlist
	HoldToken  *tokens.Token
	Queue      chan<- *Playlist
}

type PlaylistItem struct {
	ZapScript string
	Name      string
}