gallery

type FileInfo struct {
	Name    string   `json:"name"`
	ModTime int64    `json:"mtime"`
	Size    int64    `json:"size"`
	Kind    FileKind `json:"kind"`
}

type FileKind string

type FileView struct {
	Name     string // basename ("photo.jpg" or "subdir")
	Href     string // relative link
	ThumbURL string // for images, the relative thumb URL; empty for non-images
	IsDir    bool
	IsUp     bool // true for the synthetic "../" up-link entry (rendered with ↑ icon, no trailing /)
	IsImage  bool
	IsVideo  bool
	IsOther  bool

	// ParentDir is set ONLY on the up-link FileView. It is the
	// basename of the parent directory (one level up from the
	// current page). Rendered as part of the up chip's display
	// text — "Up (../{ParentDir})" — so the user sees which
	// directory they'll land in. Empty at the gallery root or
	// in a top-level subdir (parent is the gallery root, no name
	// to show). Per user request 2026-06-17.
	ParentDir string

	// Internal fields used by buildFileView to format Size/Date
	// without round-tripping through fmt in the template.
	Size string
	Date string
	Type string
}

type Gallery struct {
	// Root is the on-disk directory to render. Set automatically by
	// Caddy's `root` directive (via Provision), or can be set in JSON
	// config.
	Root string `json:"root,omitempty"`

	// Sort is the field used to order the gallery. Valid values:
	//   "mtime" (default) — newest first
	//   "name"           — alphabetical
	Sort string `json:"sort,omitempty"`

	// Template is the name of the template file to use, relative to
	// the templates dir ($GALLERY_TEMPLATES_DIR, default
	// /etc/caddy/gallery-templates). If empty, defaults to
	// "gallery.tmpl". The path is validated at Provision to
	// reject absolute paths and any traversal above the templates
	// dir (no `..` allowed). The template dir is the chroot; the
	// operator can only reference files inside it.
	Template string `json:"template,omitempty"`

	// NoThumbs disables the on-the-fly WebP thumbnail generation.
	// When true, the gallery uses the original image as the tile
	// <img src> instead of `/_thumbs/<name>.webp`. Requests to the
	// thumb URL fall through to the next handler (typically
	// file_server, which 404s since no _thumbs/ dir exists).
	// Tradeoffs: no thumb cache, no CPU cost, but the browser
	// downloads the full image per tile (bigger page payload, slower
	// load on dirs of large photos). Useful for small galleries
	// where the operator doesn't want to maintain a thumb cache.
	NoThumbs bool `json:"no_thumbs,omitempty"`

	// NoVideoThumbs disables the on-demand WebP thumbnail generation
	// for VIDEO files (extracted from the first frame via ffmpeg).
	// When true, videos still display in the gallery (with the
	// placeholder gradient + play button on each tile) but no
	// per-frame thumbnail is produced or served. When false (the
	// default), video thumbnails ARE generated IF ffmpeg is
	// available on the host — if ffmpeg is missing, video thumbs
	// fall back to the placeholder regardless of this setting
	// (there's no way to generate a frame without a tool that can
	// decode the video).
	// Caddyfile: `no_video_thumbs` (no arg → true) or
	//            `no_video_thumbs false` (re-enable).
	NoVideoThumbs bool `json:"no_video_thumbs,omitempty"`

	// PageSize is the number of image entries per page. Default
	// is 50 (set in Provision if zero). The user can override
	// per-route via the Caddyfile: `image_gallery { page_size 100 }`.
	// Validation: must be > 0. A zero or negative value is rejected
	// by UnmarshalCaddyfile (the Caddyfile parser).
	PageSize int `json:"page_size,omitempty"`

	// ThumbWidth is the maximum width in pixels of generated
	// thumbnails. The source image is fit-within-bounds (aspect
	// ratio preserved, longest edge becomes the configured value).
	// Default: 320. Caddyfile: `thumb_width 480`.
	// Validation: must be > 0; zero/negative rejected.
	ThumbWidth int `json:"thumb_width,omitempty"`

	// ThumbHeight is the maximum height in pixels of generated
	// thumbnails. Fit-within-bounds behavior — see ThumbWidth.
	// Default: 320. Caddyfile: `thumb_height 480`.
	// Validation: must be > 0.
	ThumbHeight int `json:"thumb_height,omitempty"`

	// ThumbFormat is the output format for generated thumbnails.
	// One of: "jpeg" (or "jpg"), "png", or "webp" (the current
	// default, lossless). Default: "webp". Caddyfile:
	// `thumb_format jpeg`. Validation: must be one of the three.
	ThumbFormat string `json:"thumb_format,omitempty"`

	// CacheScanMinutes is the in-memory scan cache TTL in
	// minutes. Default: 1. Caddyfile: `cache_scan 5`.
	// Validation: must be > 0.
	CacheScanMinutes int `json:"cache_scan,omitempty"`

	// ThumbTTLMinutes is the HTTP Cache-Control max-age in
	// minutes for thumb responses. Thumbs are immutable per
	// source mtime, so a long TTL is safe. Default: 1440
	// (= 24 hours, matches the previous 86400-second value).
	// Caddyfile: `thumb_ttl 60`. Validation: must be > 0.
	ThumbTTLMinutes int `json:"thumb_ttl,omitempty"`

	// Cache holds the in-memory scan cache. Initialised in Provision
	// if nil. Excluded from JSON config (runtime state only).
	Cache *ScanCache `json:"-"`
	// contains filtered or unexported fields
}

type PageData struct {
	Title       string
	PathPrefix  string // e.g. "./" — prefix for relative links
	ThumbPrefix string // e.g. "./_thumbs/" — prefix for thumb URLs

	// Three sections. OtherFiles is shown in full regardless of
	// pagination/sort (per the user's spec — it always appears
	// at the top, horizontal). Images is the paginated/sorted
	// set. The directories section is split into two
	// elements: Up (the synthetic ../ entry, rendered on its
	// own line, always first) and Subdirs (the actual subdirs,
	// rendered in a tight row with no gap between them, per
	// the user's 2026-06-17 spec).
	Up         *FileView  // the up entry, or nil at the gallery root
	Subdirs    []FileView // the actual subdirs (no up entry)
	OtherFiles []FileView
	Images     []FileView

	// Pagination
	Page     int // 1-based
	PageSize int
	// TotalImages is the total media count (images + videos)
	// — used for the pagination math and the visibility check
	// on the images grid section.
	TotalImages int
	// ImageCount is the count of image files only — used for
	// the "N images" label in the header meta line (so the
	// label is accurate; videos are no longer miscounted as
	// images). Per user request 2026-06-17: separate video
	// indicator in the header.
	ImageCount int
	// TotalVideos is the count of video files only — shown in
	// the header meta line as "N videos" (after the images
	// count, only if > 0).
	TotalVideos int
	// TotalAllFilesSize is the pre-formatted (via humanSize) total
	// size of ALL files in the directory: images + videos + other
	// files. Excludes subdirectories (which don't have a Size
	// field). Shown in the header meta line as a separate segment
	// wrapped in `//` separators, per user request 2026-06-18:
	//   "the X.X KB is the total for all files in the directory"
	// e.g. "34 images ·8 videos ·2 other files // (8.3 MB) //
	//        ·26 directories ·50 per page"
	// The `//` separators visually distinguish the size from the
	// other meta items (which use `·`). Operator sees at a glance
	// how much disk the whole directory's media + sidecar files
	// take.
	TotalAllFilesSize string
	TotalPages        int
	HasPrev           bool
	HasNext           bool
	// PageNumbers is the list of page numbers (and 0 for
	// ellipsis) to show in the Google-style bottom pagination.
	// Computed by pageNumbers(current, total). Empty when
	// total <= 1 (no pagination needed).
	PageNumbers []int

	// Sort
	Sort SortSpec
}

type ScanCache struct {
	// contains filtered or unexported fields
}

type Scanner struct {
	Root string
	Sort string // "mtime" (default) or "name"
}

type SortSpec struct {
	Field string
	Order string
}

type ThumbConfig struct {
	// Width and Height are the max-dim bounding box (in pixels)
	// for the generated thumb. The source image is fit-within-
	// bounds: aspect ratio is preserved and the longest edge
	// becomes the configured value.
	Width  int
	Height int
	// Format is the output format: "jpeg" (or "jpg"), "png", or
	// "webp" (the default, lossless). Encoded with stdlib
	// image/jpeg (quality 75), stdlib image/png, or
	// github.com/HugoSmits86/nativewebp respectively.
	Format string
}