gallery

type BreadcrumbSegment struct {
	Name string
	Href string
}

type ExifData struct {
	CameraMake   string
	CameraModel  string
	LensModel    string
	DateTaken    string // formatted "2024-11-08 06:23:14" (already EXIF format)
	ExposureTime string // formatted "1/250 s", "2 s", etc.
	Aperture     string // formatted "f/2.8"
	ISO          string // formatted "ISO 400"
	FocalLength  string // formatted "50 mm"
}

type FileInfo struct {
	Name    string   `json:"name"`
	ModTime int64    `json:"mtime"`
	Size    int64    `json:"size"`
	Kind    FileKind `json:"kind"`
	// Width and Height are the pixel dimensions of the source
	// image or video (the file the thumbnail was generated
	// from). Zero means "dimensions not available" — for
	// unsupported formats (AVIF, HEIC, SVG) the scanner
	// skips readDimensions. Per user request 2026-06-27:
	// dimensions are read at scan time and cached alongside
	// the rest of the file metadata.
	Width  int `json:"width,omitempty"`
	Height int `json:"height,omitempty"`
	// CountItems is the number of NON-directory entries
	// (files, symlinks-to-files, broken symlinks, etc.) inside
	// this subdirectory. Only meaningful for KindDir entries.
	// Populated by Scanner.Scan; the count is computed by
	// reading the subdir's contents (one extra os.ReadDir
	// syscall per subdir, then discarded).
	// Exif is the CAMERA-subset EXIF metadata for this file
	// (only meaningful for image files). Per user request
	// 2026-06-29: EXIF is read LAZILY (on lightbox open via
	// the ?exif=1 endpoint), NOT at scan time. This field
	// is always nil from the scanner — it's only set by
	// the EXIF endpoint handler when the lightbox asks.
	// Keeping the field for backward compatibility with
	// any code that might check it; the rendered HTML
	// no longer references FileInfo.Exif.
	//
	// The legacy CAMERA subset (Make, Model, Lens,
	// DateTimeOriginal, ExposureTime, FNumber,
	// ISOSpeedRatings, FocalLength) is preserved; GPS is
	// never extracted. See exif.go for details.
	Exif *ExifData `json:"exif,omitempty"`
	// Per user request 2026-07-02: VideoMeta holds the
	// extracted video metadata (duration, container,
	// codecs, bitrate, framerate). Only meaningful for
	// KindVideo entries; nil for non-videos. Populated
	// lazily via the same background-enrich pipeline
	// that handles EXIF (when the scanner runs, it
	// can also queue a video metadata extraction).
	VideoMeta  *VideoMeta `json:"video_meta,omitempty"`
	CountItems int        `json:"count_items"`
	// CountDirs is the number of directories inside this
	// subdirectory. Includes real directories AND symlinks
	// that point to directories (per user request 2026-06-27).
	// Only meaningful for KindDir entries.
	CountDirs int `json:"count_dirs"`
}

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
	// Per user request 2026-06-30: DisplayName is the name
	// shown to the visitor as a hover tooltip on each
	// thumbnail. It's the filename without the extension,
	// with underscores ("_") and hyphens ("-") replaced by
	// spaces — so "misty_bamboo_forest_path.jpg" becomes
	// "misty bamboo forest path" (human-readable). Used in
	// the HTML title attribute (native browser tooltip) AND
	// in a CSS-only ::after pseudo-element tooltip (custom
	// styled, appears on hover with no delay).
	DisplayName string

	// 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

	// Per user request 2026-07-01: SizePct is the relative size
	// of this file/directory as a percentage of the largest
	// in the same section (dirs or others). 0-100, where 100 is
	// the largest. The template puts this on the .col-size cell
	// as a CSS custom property (--size-pct) so a ::before pseudo-
	// element can draw a light-grey bar across the cell width
	// proportional to the size. Set by computeSizePercentages()
	// after buildFileViews() for the dirs and others slices.
	// Zero for sections with a single item (or all items the
	// same size — the first item gets 100, the rest get less).
	SizePct int

	// ModTime is the raw int64 timestamp (nanoseconds since
	// epoch). Used by the JS header-sort feature to sort
	// the others table by Modified. Formatted display goes
	// through Date (the human-readable form).
	ModTime int64

	// Width and Height are the pixel dimensions of the source
	// image/video. Zero for unsupported formats (AVIF, HEIC,
	// SVG — per user request 2026-06-27). Dimensions is the
	// formatted "WIDTH × HEIGHT" string for the watermark;
	// empty when Width or Height is zero.
	Width      int
	Height     int
	Dimensions string

	// Exif is no longer populated by the scanner. Per
	// user request 2026-06-29: EXIF is read LAZILY when
	// the lightbox opens (via the ?exif=1 endpoint). The
	// card overlay no longer shows the "EXIF" pill (we
	// don't know if EXIF exists until the lightbox
	// fetches it). The lightbox JS fetches the EXIF
	// separately and populates the EXIF panel.
	// This field is kept for backward compatibility; it's
	// always nil. The ExifData type is still defined for
	// the JSON shape returned by the ?exif=1 endpoint.
	Exif *ExifData
	// ExifAttrs is the pre-rendered EXIF attribute string
	// (e.g. ` data-exif-camera-make="Canon" data-exif-camera-model="EOS R5" ...`).
	// Empty if no EXIF. Per optimization 2026-06-30: this
	// replaces 8 separate template field accesses
	// ({{.Exif.CameraMake}}, etc.) — each of which was a
	// reflection-based field lookup. The template now just
	// does {{.ExifAttrs}} which is a simple struct field
	// access (no reflection, no function call).
	ExifAttrs template.HTMLAttr // pre-rendered EXIF data attributes (trusted HTML attribute — values are html.EscapeString'd, template trusts the result)

	// Per user request 2026-07-02: VideoMeta holds the
	// extracted video metadata (duration, container,
	// codecs, bitrate, framerate). Only meaningful for
	// KindVideo entries; nil for non-videos.
	VideoMeta *VideoMeta
	// VideoMetaAttrs is the pre-rendered `data-video-*`
	// attribute string (similar to ExifAttrs for EXIF).
	// Empty if no video metadata. The lightbox JS
	// reads these attributes and populates a separate
	// "video metadata" panel.
	VideoMetaAttrs template.HTMLAttr // pre-rendered video data attributes (trusted HTML — values are html.EscapeString'd)

	// CardHTML is the entire card markup pre-rendered as a
	// single string. Per optimization 2026-07-01: instead of
	// the template walking 60×(~50) nodes for 60 cards (the
	// biggest render bottleneck per the CPU profile), Go
	// builds the card HTML once per file in buildFileView,
	// and the template does {{.CardHTML}} — a single
	// template.HTML substitution per card (zero reflection per
	// card, just string interpolation).
	//
	// Per-page savings: ~60% of template-execute time
	// (~1.5ms shaved off a 3ms render = ~50% total
	// render speedup for a 60-card page).
	CardHTML template.HTML

	// CountItems is the number of NON-directory entries inside
	// this subdirectory (files + symlinks to files + broken
	// symlinks, etc.). Only set on directory entries (IsDir=true).
	// Populated by buildFileView from FileInfo.CountItems
	// (set by Scanner.Scan via countSubdirStats).
	CountItems int
	// CountDirs is the number of directories inside this
	// subdirectory. Includes real directories AND symlinks to
	// directories (per user request 2026-06-27). Only set on
	// directory entries.
	CountDirs int
}

type FilterGroup struct {
	Label    string // "Images", "Videos", "Other"
	Options  []FilterOption
	Selected int // number of Options with Selected=true
	Total    int // len(Options)
}

type FilterOption struct {
	Ext        string // lowercase, with leading dot, e.g. ".jpg" (or "." sentinel for files without extensions (".jpg" form value; the dot-prefix is consistent with other extensions like ".jpg"); see FilterOption.IsNone)
	DisplayExt string // canonical-case form for display, e.g. "JPG" (vs "jpg"), or "(none)" for files without extensions
	Count      int    // files in the current directory with this ext
	Selected   bool   // currently in the active ?type= filter
	// Per user request 2026-06-30: IsNone marks the
	// "(none)" option for files without an extension.
	// The form uses a sentinel value (".") instead of
	// an empty string because browsers skip empty checkboxes
	// when serializing the form, which would lose the
	// distinction between "unchecked" and "checked but empty".
	IsNone bool // true for the (none) entry (files without an extension)
}

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

	// PathPrefix is the URL mount prefix for the gallery
	// (e.g. "images" if the gallery is mounted at /images/*
	// in the Caddyfile). It is used by the breadcrumb so
	// the first segment matches what the user sees in the
	// URL. Defaults to filepath.Base(Root) if empty.
	PathPrefix string
	// RootName is the operator-configurable display name for
	// the first breadcrumb segment (the gallery's root). Set
	// in the Caddyfile via . If empty,
	// the resolved rootName (set in Provision) defaults to
	// "media root" — a generic name that works for any gallery.
	RootName string

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

	// Template is the name of the template file to use, relative to
	// the 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

	// ImageExts is the set of file extensions the gallery treats
	// as images. Set from the  Caddyfile subdirective
	// (space-separated, case-insensitive, with or without leading
	// dot). If empty (the default), the plugin uses a built-in list
	// of common image extensions (jpg, jpeg, png, gif, webp).
	// HEIC, AVIF, and SVG are NOT in the default list — Go's
	// stdlib can't decode them. Operators can still add them
	// via `image_types .heic .avif .svg` if they have external
	// tooling to handle these formats. Provision() converts this
	// list to a map for the Scanner to use.
	ImageExts []string

	// VideoExts is the set of file extensions the gallery treats
	// as videos. Set from the  Caddyfile subdirective
	// (same syntax as image_types). Empty (default) uses the
	// built-in video list (mp4, webm, m4v, mov, mkv, avi, ogv, ogg).
	VideoExts []string

	// NoThumbs disables the on-the-fly WebP thumbnail generation.
	// When true, the gallery uses the original image as the tile
	// <img src> instead of . 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).
	//
	// Per user request 2026-07-02: NoThumbs now defaults to
	// TRUE so the gallery behaves like caddy's stock
	// file_server browse by default (no on-the-fly thumb
	// generation, no thumb cache, no ffmpeg CPU overhead).
	// Operators who want the rich thumbnail UX opt in
	// via `no_thumbs false` in the Caddyfile.
	NoThumbs bool
	// NoThumbsSet is true when the operator explicitly set
	// no_thumbs in the Caddyfile. Used by Provision to
	// distinguish "explicit false" (preserve the false)
	// from "no directive" (apply the default true).
	NoThumbsSet bool

	// 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 arg → true) or
	//             (re-enable).
	NoVideoThumbs bool

	// NoExif controls whether EXIF metadata is read from
	// image files. Per user request 2026-07-02: defaults
	// to TRUE so the gallery behaves like caddy's stock
	// file_server browse (no extra dependencies / I/O
	// required by default). When true (the default), the
	// scanner skips the readExif call entirely (no I/O,
	// no parsing) — FileInfo.Exif is left nil for all
	// files. The card overlay shows no "EXIF" pill (the pill
	// only renders when Exif is non-nil) and the lightbox
	// shows no EXIF panel. When false, EXIF is read for
	// every image file at scan time (EAGER loading — see
	// scanner.go and exif.go).
	//
	// Operators who want the rich EXIF metadata UX can
	// opt back in via the Caddyfile:
	//   no_exif false    # re-enable EXIF reading
	//
	// The "no_exif" directive is now a misnomer (since it's
	// the default), but we keep the name for backward
	// compatibility — operators who already set "no_exif"
	// in their Caddyfile see no change. The presence of
	// the directive with no arg still means "disable" (i.e.
	// set to true), and the operator can use "no_exif false"
	// to opt back in to reading EXIF.
	//
	// Useful for enabling EXIF:
	//   - Metadata-rich photo galleries (camera/lens info)
	//   - Any operator who wants the EXIF pill on cards
	//   - Note: EXIF does NOT include GPS by default (see
	//     exif.go — GPS is never extracted).
	// Caddyfile: no_exif (no arg → true) or no_exif false
	// (re-enable EXIF reading).
	NoExif bool
	// NoExifSet is true when the operator explicitly set
	// no_exif in the Caddyfile (including with value
	// "false"). Used by Provision to distinguish
	// "operator set to true" / "operator set to false" /
	// "operator didn't set (use the default true)". The
	// Caddyfile parser sets this flag whenever the
	// directive appears, even with value "false".
	NoExifSet bool
	// Per user request 2026-07-02: NoMeta controls whether
	// video metadata is read (duration, container, codecs,
	// bitrate, framerate extracted via ffprobe). Defaults
	// to TRUE so the gallery behaves like caddy's stock
	// file_server browse (no extra ffprobe dependency
	// required by default). This is a separate flag from
	// NoExif — NoExif affects image EXIF; NoMeta affects
	// video metadata. When true (the default), the scanner
	// skips the readVideoMetaCached call entirely (no
	// ffprobe subprocess, no .vmeta sidecar writes, no
	// parsing). FileInfo.VideoMeta is left nil for all
	// files, so the lightbox META panel stays hidden and
	// the "META" pill on video cards is not rendered.
	//
	// Operators who want the rich video metadata UX can
	// opt back in via the Caddyfile:
	//   no_meta false    # re-enable video metadata extraction
	//
	// As with NoExif, the directive name "no_meta" is a
	// bit of a misnomer since it now defaults to true, but
	// we keep the name for backward compatibility.
	// Caddyfile: no_meta (no arg → true) or no_meta false
	// (re-enable video metadata extraction).
	NoMeta bool
	// NoMetaSet is true when the operator explicitly set
	// no_meta in the Caddyfile. Used by Provision to
	// distinguish "operator set to true" / "operator set
	// to false" / "operator didn't set (use the default
	// true)". The Caddyfile parser sets this flag whenever
	// the directive appears, even with value "false".
	NoMetaSet bool

	// 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: .
	// Validation: must be > 0. A zero or negative value is rejected
	// by UnmarshalCaddyfile (the Caddyfile parser).
	PageSize int
	// PageSizes is the list of page sizes the visitor can
	// choose from in the per-page dropdown (e.g. [30, 60, 120,
	// "all"]). Set in the Caddyfile via
	// (space-separated; "all" as a token means "show all items
	// in one page" - only included if explicitly listed).
	// If empty (default), the resolved PageSizes (set in
	// Provision) is [30, 60, 120, "all"]. The CURRENT page size
	// is set via the URL ?page_size=N parameter, which is
	// validated against this list (unknown values fall back to
	// the first item).
	PageSizes []string

	// SearchMatch controls how filenames are matched against
	// the search query. Two values:
	//   "substring" (default) — the query can match anywhere in
	//     the filename. "cat" matches "scatter.png".
	//   "word" — the query must match the start of a word
	//     boundary. "cat" matches "cat.jpg" and "my_cat.webp"
	//     but NOT "scatter.png". Uses the same word boundaries
	//     as the URL/PATH separators (_, -, space).
	//
	// Caddyfile:  (or omit for default).
	// Validation: must be one of the two; any other value
	// defaults silently to "substring" in Provision.
	SearchMatch string

	// 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: .
	// Validation: must be > 0; zero/negative rejected.
	ThumbWidth int

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

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

	// CacheScanMinutes is the in-memory scan cache TTL in
	// minutes. Default: 1440 (24 hours).
	//
	// Per user request 2026-07-01: the scan cache's primary
	// invalidation is the DIRECTORY MTIME (checked on every
	// Get). Adding or removing a file changes the dir mtime,
	// so the cache automatically invalidates. The TTL is a
	// SAFETY NET for edge cases (clock skew, manual mtime
	// changes, stat cache invalidation). Setting it to 24
	// hours means the cache stays warm for typical
	// interactive use without forcing periodic re-scans that
	// would re-do the os.ReadDir + per-file stat() work.
	//
	// Caddyfile: . Validation: must be > 0.
	CacheScanMinutes int

	// 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: . Validation: must be > 0.
	ThumbTTLMinutes int
	// MaxCacheSizeMB is the on-disk thumb cache size cap in
	// MB. When the cache directory exceeds this size, the
	// oldest thumbs (by file mtime) are evicted until the
	// cache is at 80% of the cap (20% headroom to avoid
	// thrashing). Default: 1024 (= 1 GB). Set to 0 to
	// disable the cap entirely (unbounded cache — current
	// pre-feature behavior).
	//
	// The cap is enforced by:
	//   1. An on-write check after each thumb is written
	//      (cheap, runs in a goroutine, doesn't block the
	//      request that triggered the cache write).
	//   2. A background sweep every 30 minutes (catches the
	//      case where the cache grows without new writes).
	//   3. An initial sweep at startup if the cache is
	//      already over the cap (so the operator's existing
	//      over-cap cache gets trimmed down on the first
	//      restart after they set the cap).
	//
	// Eviction policy: FIFO by file mtime. The cache file
	// names are sha256(source path) — opaque hex, not
	// sorted. We use the file's mtime on disk (which is the
	// WRITE time) to determine the oldest. For a true LRU,
	// enable filesystem atime or use a separate LRU log.
	MaxCacheSizeMB int
	// MaxCacheSizeSet is true when the operator explicitly
	// set max_cache_size_mb in the Caddyfile (including
	// the value 0). Used to distinguish "operator set 0
	// (no cap)" from "operator didn't set the directive
	// (use the default)". The default (when neither
	// Caddyfile nor JSON sets it) is 1024 MB.
	MaxCacheSizeSet bool

	// DefaultLanguage is the fallback locale when neither
	// the URL parameter, cookie, nor Accept-Language header
	// produces a match. Per user request 2026-07-04:
	// operators can set this in the Caddyfile via
	//   default_language = "de"
	// Empty string falls back to "en". Validated at
	// Provision time (must match a known locale or be empty).
	// Per user request 2026-07-04: visitors can ALWAYS
	// override this with ?lang=<locale> or the cookie,
	// regardless of what the operator sets here.
	DefaultLanguage string

	// Cache holds the in-memory scan cache. Initialised in Provision
	// if nil. Excluded from JSON config (runtime state only).
	Cache *ScanCache

	// CacheStatsTracker records evictions and exposes the
	// most recent cacheStats snapshot via atomic.Pointer.
	// Initialised in Provision. Used by evictIfOver
	// (recordEvictions) and the stats-refresh goroutine
	// (snapshot + atomic swap). Excluded from JSON config.
	CacheStatsTracker *cacheStatsTracker
	// 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
	// Query is the current URL query (sort, filter, page, breadcrumb, etc.) — passed to the template so the page-size form can include hidden inputs to preserve other params on submit.
	Query url.Values
	// CacheStatsXX, CacheStatsYY, CacheStatsZZ, CacheStatsAA
	// are the four hex values displayed in the footer:
	//
	//   XX  = cache usage percent, 00-FF (or "∞" if
	//         MaxCacheSizeMB is 0 / unbounded)
	//   YY  = peak evictions in any 1-hour bucket in the
	//         last 24 hours, 00-FF
	//   ZZ  = peak evictions in any 1-hour bucket in the
	//         last 7 days, 00-FF
	//   AA  = peak evictions in any 1-hour bucket in the
	//         last 28 days (4 weeks), 00-FF
	//
	// When MaxCacheSizeMB is 0, XX is rendered as the
	// infinity symbol (∞) and YY/ZZ/AA are always "00".
	//
	// Per user request 2026-06-27. Refreshed every 30 sec
	// by the stats-refresh goroutine in Provision (atomic
	// pointer swap; readers don't lock).
	CacheStatsXX string
	CacheStatsYY string
	CacheStatsZZ string
	CacheStatsAA string
	// Locale is the visitor's resolved locale (e.g. "en",
	// "de", "ja"). Detected by DetectLocale using URL param
	// > cookie > Accept-Language > operator default.
	// Per user request 2026-07-04: the template uses this
	// for the <html lang="..."> attribute (so screen
	// readers and CSS :lang() selectors work correctly)
	// and for any locale-aware formatting. Defaults to
	// "en" if empty.
	Locale string
	// Translator is the i18n resolver passed into the
	// template via the "t" function. Per user request
	// 2026-07-04: when nil (which shouldn't happen in
	// production but might in unit tests), the template
	// function falls back to English-only lookups via
	// a default-constructed Translator. Keeping this
	// field on PageData rather than threading it through
	// the func map separately lets the same data struct
	// flow through both server-side tests and the live
	// page render without code changes.
	Translator *Translator
	// AvailableLocales is the sorted list of supported
	// locales. Used by the language picker (rendered in
	// Phase 3 / localStorage persistence commit) and by
	// the <html lang="..."> attribute selector. Empty
	// if no translator is wired up.
	AvailableLocales []string
	// SearchQuery is the raw ?q= value (for the search
	// input's `value=""` attribute and for hidden inputs
	// that preserve the query on form submit).
	SearchQuery string
	// SearchMatch is the operator-configured filename matching
	// rule for the search feature. Either "substring" (the
	// default — query can match anywhere) or "word" (query
	// must match the start of a word boundary). The template
	// uses this to render a data-search-match attribute on
	// the search input; the inline JS reads the attribute
	// and switches the matching rule accordingly.
	SearchMatch string
	// IsServerSearchActive is true when the page was
	// rendered with ?q= in the URL (the visitor clicked
	// "Search all" or typed into the URL bar). In this case
	// the file list is ALREADY filtered server-side; the
	// header shows "Media (showing N of M)" where M is the
	// total filtered count in the directory. False when
	// the visitor is just typing in the search box (the
	// client-side filter is doing the work, M = N).
	IsServerSearchActive bool
	// FilteredTotal is the total number of files in the
	// directory that match the active ?q= search. Only
	// meaningful when IsServerSearchActive is true; zero
	// otherwise. The header uses this as the "M" value in
	// "showing N of M".
	FilteredTotal int
	// OnPageMatchedCount is the number of files visible on
	// the current page (already after the server-side
	// filter). The header uses this as the "M" value in
	// "search showing M of N <em>This page</em>" when
	// search is active.
	OnPageMatchedCount int
	// OnPageTotalCount is the number of items that would be
	// on this page if no search filter were applied. For
	// most pages this is the configured pageSize. For the
	// last page, it's the truncated count (e.g. 29 instead
	// of 60 if there are 89 total items). The header uses
	// this as the "N" value in "search showing M of N
	// <em>This page</em>".
	OnPageTotalCount int
	// PageSizes is the list of per-page options the visitor
	// can choose from in the dropdown (e.g. [30, 60, 120, "all"]).
	// Configured via the `page_sizes` Caddyfile directive;
	// defaults to [30, 60, 120, "all"].
	PageSizes []string
	// TotalImages is the total media count (images + videos)
	// AFTER the search/type filters have been applied. Used
	// for the pagination math and the visibility check on
	// the images grid section. If the user has ?q=foo in
	// the URL, this is the count of items matching "foo".
	TotalImages int
	// DirectoryTotal is the total media count in the
	// directory BEFORE any search/type filters are applied.
	// Used for the "Media (N -" prefix in the section
	// header so the visitor sees the total directory size
	// at a glance even while searching. Per user request
	// 2026-06-30: the prefix should keep the directory
	// total (not the filtered total) so the user knows
	// they're seeing N out of TOTAL.
	DirectoryTotal 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
	// ImageStart and ImageEnd are the 1-based range of images
	// shown on the current page (e.g. 1-60 for page 1, 61-89
	// for page 2). Used in the media section header: "Media
	// (89 - Showing 1-60)". Both are 0 if there are no images.
	ImageStart int
	ImageEnd   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
	// TotalFiles is the sum of all files in the directory:
	// ImageCount + TotalVideos + len(OtherFiles). Computed
	// in RenderPage (not the template) and shown at the start
	// of the header meta line as "N files" (per user request
	// 2026-06-19: a quick "how many files are in this dir"
	// answer at the top of the meta line).
	TotalFiles 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

	// Breadcrumb is the list of path segments from the
	// gallery root to the current directory. Each segment has
	// a Name (human-readable) and an Href (relative URL).
	// The first segment is the gallery root; the last is the
	// current directory (rendered as plain text, not a link).
	Breadcrumb []BreadcrumbSegment

	// Sort
	Sort SortSpec

	// TypeFilter is the parsed ?type= query param (set of
	// file extensions to show). nil = no filter (show all
	// files). An empty (non-nil) map = "show nothing"
	// (the filter UI shows the empty state). Use
	// IsTypeFilterActive to distinguish "no filter" from
	// "filter that selects nothing" in the UI.
	TypeFilter map[string]bool

	// IsTypeFilterActive is true if the URL has a non-empty
	// ?type= query param. This is the source of truth for
	// whether the filter UI should show the "filtered" state.
	IsTypeFilterActive bool

	// TypeFilterQuery is the raw ?type= value (or "" if no
	// filter). Pass through to the filter UI's form action
	// so the user can re-submit their selection.
	TypeFilterQuery string

	// FilterImageOptions / FilterVideoOptions / FilterOtherOptions
	// are the three filter dropdowns (Images / Videos / Other).
	// Each contains the extensions present in the current
	// directory, with their counts, marked as Selected if
	// currently in the active filter. The UI renders these
	// as three side-by-side dropdowns + an Apply button.
	FilterImageOptions FilterGroup
	FilterVideoOptions FilterGroup
	FilterOtherOptions FilterGroup
}

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

type Scanner struct {
	Root      string
	Sort      string // "mtime" (default) or "name"
	ImageExts map[string]bool
	VideoExts map[string]bool
	// NoExif, when true, disables the readExif call for
	// image files (no I/O, no parsing). Set by the
	// Gallery's no_exif Caddyfile directive; passed
	// through ScanCache.Get to the per-directory Scanner.
	// When false (the default), EXIF is read eagerly at
	// scan time. See gallery.go for the full rationale.
	NoExif bool
	// NoMeta, per user request 2026-07-02: a SEPARATE flag
	// from NoExif. NoExif affects image EXIF; NoMeta
	// affects video metadata extraction (duration,
	// container, codecs, bitrate, framerate via ffprobe).
	// When true, the enrich step skips the
	// readVideoMetaCached call entirely (no ffprobe
	// subprocess, no .vmeta sidecar writes, no parsing).
	// Useful for galleries with many videos where the
	// operator doesn't need the metadata enrichment.
	// See gallery.go for the full rationale.
	NoMeta bool
	// ThumbCacheDir is the on-disk thumb cache dir. When set
	// (always set in production, via thumbCacheDir() in
	// gallery.go), the scanner uses readDimensionsCached to
	// avoid re-parsing source image headers on every scan.
	// The source dimensions are stored in a sidecar file
	// alongside the thumb. See readDimensionsCached in
	// dimensions.go for the cache file format.
	ThumbCacheDir string
	// ThumbFormat is the thumb file extension (e.g. "webp").
	// Used to derive the sidecar path. Defaults to "webp" if
	// empty (so unit-mode tests that don't set up the full
	// cache dir still work).
	ThumbFormat string
}

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
	// MaxCacheSizeMB is the configured cache cap (from
	// the Caddyfile). 0 = no cap (the pre-feature
	// behavior). Passed to the eviction helper after
	// each successful cache write.
	MaxCacheSizeMB int
	// CacheStatsTracker records eviction counts so the
	// footer can show peak evictions per period. nil is
	// safe (recordEvictions is a no-op). Set in
	// Provision; passed through ThumbConfig to
	// GenerateOrLoadThumb.
	CacheStatsTracker *cacheStatsTracker
}

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

type VideoMeta struct {
	Duration   string // "1:23" or "1:23:45"
	Container  string // "mov,mp4,m4a,3gp,3g2,mj2" (ffprobe output)
	VideoCodec string // "h264", "vp9", "av1", etc.
	AudioCodec string // "aac", "opus", "vorbis", etc. (empty if no audio)
	Bitrate    string // "5.2 Mbps", "842 kbps" (human-readable)
	Framerate  string // "24 fps", "29.97 fps" (human-readable)
}