engine

type Badge struct {
	Text    string       `yaml:"text"`
	Variant BadgeVariant `yaml:"variant"`
}

type BadgeVariant string

type BreadcrumbItem struct {
	Label   string
	URL     string
	Current bool
}

type BuildLogEntry struct {
	Source  string // e.g. "sitemap", "search", "social-cards"
	Message string
}

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

type BuildResult struct {
	PageCount int
	Duration  time.Duration
	Warnings  []ValidationWarning
	OutputDir string

	// Summary stats (populated by full Build(), zero for incremental ContentRebuild).
	PaginatorPages  int
	Collections     int
	BundleAssets    int
	StaticFiles     int
	ProcessedImages int
	AliasCount      int
	SitemapCount    int

	// Build logging.
	LogMessages  []BuildLogEntry
	PhaseTimings []PhaseTiming
}

type CollectedLink struct {
	Href    string
	IsImage bool
}

type Collection struct {
	Name      string
	Title     string
	Config    *CollectionConfig
	Pages     []*Page
	Featured  []*Page // subset of Pages with frontmatter `featured: true`
	Sections  []*Section
	NavTree   *NavTree            // default language nav tree (backward compat)
	NavTrees  map[string]*NavTree // per-language nav trees (i18n)
	IndexPage *Page
	IsTabbed  bool       // true when docs tabs are auto-detected or forced
	Tabs      []*DocsTab // ordered by weight, then title

	// Versioning
	Versioning        *VersionConfig
	CompositeNavTrees map[string]*NavTree   // keyed by langVersionKey(lang, ver) for versioned collections
	CompositeTabSets  map[string][]*DocsTab // keyed by langVersionKey(lang, ver) for versioned+tabbed collections
}

type CollectionConfig struct {
	SortBy     string
	SortOrder  string
	Layout     LayoutType
	Permalink  string
	Paginate   int
	Feed       bool
	Sidebar    *SidebarConfig
	TOC        *TOCConfig
	PrevNext   *PrevNextConfig
	Tabs       *bool          // nil = auto-detect, true = force tabs, false = disable tabs
	Versioning *VersionConfig // nil = no versioning
}

type DocsTab struct {
	Title       string
	Description string
	Icon        string // emoji, icon name, or SVG path
	Slug        string // directory name, used for URL prefix matching
	Order       int
	Permalink   string   // URL of the tab's index page
	Section     *Section // the top-level section backing this tab
	NavTree     *NavTree
	NavTrees    map[string]*NavTree // per-language (i18n)
	Pages       []*Page
	IndexPage   *Page
}

type EditURLValue struct {
	Disabled  bool
	CustomURL string
}

type FieldDef struct {
	Type      string   `yaml:"type"       json:"type"` // "string", "int", "float", "bool", "date", "list", "enum"
	Label     string   `yaml:"label"      json:"label,omitempty"`
	Required  bool     `yaml:"required"   json:"required,omitempty"`
	Default   any      `yaml:"default"    json:"default,omitempty"`
	Min       *float64 `yaml:"min"        json:"min,omitempty"`
	Max       *float64 `yaml:"max"        json:"max,omitempty"`
	MaxLength *int     `yaml:"max_length" json:"maxLength,omitempty"`
	Options   []string `yaml:"options"    json:"options,omitempty"` // for enum type
}

type Frontmatter struct {
	FrontmatterIdentity `yaml:",inline"`
	FrontmatterMeta     `yaml:",inline"`
	Sidebar             FrontmatterSidebar `yaml:"sidebar"`
	TOC                 FrontmatterTOC     `yaml:"toc"`
	FrontmatterNav      `yaml:",inline"`

	Tags        []string       `yaml:"tags"`
	Categories  []string       `yaml:"categories"`
	Transparent bool           `yaml:"transparent"`
	Hero        *HeroConfig    `yaml:"hero"`
	Icon        string         `yaml:"icon"`
	Head        []HeadTag      `yaml:"head"`
	Banner      *PageBanner    `yaml:"banner"`
	Cascade     map[string]any `yaml:"cascade"`
	Params      map[string]any `yaml:"params"`
}

type FrontmatterIdentity struct {
	Title       string    `yaml:"title"`
	Slug        string    `yaml:"slug"`
	Date        time.Time `yaml:"date"`
	Updated     time.Time `yaml:"updated"`
	PublishDate time.Time `yaml:"publish_date"`
	ExpiryDate  time.Time `yaml:"expiry_date"`
	Aliases     []string  `yaml:"aliases"`
	Layout      string    `yaml:"layout"`
	Type        string    `yaml:"type"`
	Template    string    `yaml:"template"`
}

type FrontmatterMeta struct {
	Draft       bool          `yaml:"draft"`
	Description string        `yaml:"description"`
	Image       string        `yaml:"image"`
	Summary     string        `yaml:"summary"`
	Render      *bool         `yaml:"render"`
	Pagefind    *bool         `yaml:"pagefind"`
	ShowUpdated *bool         `yaml:"show_updated"`
	EditURL     *EditURLValue `yaml:"edit_url"`
}

type FrontmatterNav struct {
	Prev *NavOverride `yaml:"prev"`
	Next *NavOverride `yaml:"next"`
}

type FrontmatterSchema struct {
	Fields map[string]FieldDef `yaml:"fields" json:"fields"`
}

type FrontmatterSidebar struct {
	Order  int               `yaml:"order"`
	Label  string            `yaml:"label"`
	Hidden bool              `yaml:"hidden"`
	Group  string            `yaml:"group"`
	Attrs  map[string]string `yaml:"attrs"`
	Badge  Badge             `yaml:"badge"`
	Icon   string            `yaml:"icon"`
}

type FrontmatterTOC struct {
	Enabled  *bool `yaml:"enabled"`
	MinLevel int   `yaml:"min_level"`
	MaxLevel int   `yaml:"max_level"`
}

type GlobalNav struct {
	Items []GlobalNavItem
}

type GlobalNavItem struct {
	Label      string
	URL        string
	Collection string
	IsActive   bool
	External   bool
}

type HeadTag struct {
	Tag     string            `yaml:"tag"`
	Attrs   map[string]string `yaml:"attrs"`
	Content string            `yaml:"content"`
}

type Heading struct {
	Level int
	ID    string
	Text  string
}

type HeroAction struct {
	Text    string            `yaml:"text"`
	Link    string            `yaml:"link"`
	Variant string            `yaml:"variant"`
	Icon    string            `yaml:"icon"`
	Attrs   map[string]string `yaml:"attrs"`
}

type HeroCTAData struct {
	Label string
	URL   string
}

type HeroCodeData struct {
	Title    string
	Language string
	Body     string
}

type HeroConfig struct {
	Title   string       `yaml:"title"`
	Tagline string       `yaml:"tagline"`
	Image   *HeroImage   `yaml:"image"`
	Actions []HeroAction `yaml:"actions"`
}

type HeroData struct {
	Eyebrow      string
	Title        string
	Subtitle     string
	CTA          *HeroCTAData
	SecondaryCTA *HeroCTAData
	Stats        []HeroStatData
	Code         *HeroCodeData
	Image        *HeroImageData
	Background   string
}

type HeroImage struct {
	Src   string `yaml:"src"`
	Light string `yaml:"light"`
	Dark  string `yaml:"dark"`
	Alt   string `yaml:"alt"`
}

type HeroImageData struct {
	Src   string
	Light string
	Dark  string
	Alt   string
	HTML  template.HTML
}

type HeroStatData struct {
	Value string
	Label string
}

type HomepageData struct {
	Template string
	Hero     HeroData
}

type IconLicense struct {
	Prefix string
	Title  string
	SPDX   string
	URL    string
}

type Language struct {
	Code   string
	Name   string
	Dir    string // "ltr" or "rtl"
	Weight int
}

type LayoutType string

type MarkdownRenderer interface {
	Render(markdown string) (RenderResult, error)
}

type NavNode struct {
	Label       string
	URL         string
	Slug        string
	Order       int
	Position    int
	Children    []*NavNode
	Parent      *NavNode
	Depth       int
	IsActive    bool
	IsOpen      bool
	HasActive   bool
	DefaultOpen bool
	Page        *Page
	Attrs       map[string]string
	Icon        string
}

type NavOverride struct {
	Disabled bool   `yaml:"-"`
	Slug     string `yaml:"-"`
	Link     string `yaml:"link"`
	Label    string `yaml:"label"`
}

type NavTree struct {
	Root       *NavNode
	Flat       []*NavNode
	TotalPages int
	MaxDepth   int
}

type NodeKind string

type Page struct {
	PageIdentity
	PageContent
	PageMeta
	PageRelationships
	PageTaxonomy
	Sidebar PageSidebar
	TOC     PageTOC
	PageI18n
	PageVersioning

	NavNode   *NavNode
	Resources []Resource
	Params    map[string]any
}

type PageBanner struct {
	Content string `yaml:"content"`
	Variant string `yaml:"variant"` // note | tip | caution | danger (defaults to "note")
	Icon    string `yaml:"icon"`    // Lucide icon name; overrides the variant's default icon
}

type PageContent struct {
	Content           template.HTML
	Summary           template.HTML
	RawContent        string
	ContentDigest     string // hex digest of raw file bytes (for incremental rebuild skip)
	FrontmatterDigest string // hex digest of serialized frontmatter map (body-only change detection)
	WordCount         int
	ReadingTime       int
	Headings          []Heading
	HasCodeBlocks     bool
	HasImages         bool
}

type PageI18n struct {
	Lang            string
	LangRelPath     string
	Translations    []*Page
	AllTranslations []*Page
	IsFallback      bool
}

type PageIdentity struct {
	Title        string
	Slug         string
	Date         time.Time
	Updated      time.Time
	PublishDate  time.Time
	ExpiryDate   time.Time
	Permalink    string
	RelPermalink string
	Kind         NodeKind
	FilePath     string
	RelPath      string
}

type PageMeta struct {
	Draft       bool
	Description string
	Image       string
}

type PageRelationships struct {
	Collection *Collection
	Section    *Section
	PrevPage   *Page
	NextPage   *Page
	Siblings   []*Page
	Backlinks  []*Page
}

type PageSidebar struct {
	Order  int
	Label  string
	Hidden bool
	Group  string
	Attrs  map[string]string
	Badge  Badge
	Icon   string
}

type PageTOC struct {
	Enabled  *bool
	MinLevel int
	MaxLevel int
}

type PageTaxonomy struct {
	Tags       []string
	Categories []string
	Aliases    []string
	Extra      map[string][]string
}

type PageVersioning struct {
	Version        string
	VersionRelPath string
	VersionPeers   []*Page
}

type PaginationLink struct {
	URL   string
	Title string
}

type PaginationLinks struct {
	Prev *PaginationLink
	Next *PaginationLink
}

type Paginator struct {
	Pages        []PaginationLink // Numbered links (one per page of results)
	CurrentPages []*Page          // Slice of content pages visible on this pagination page
	Current      int              // 1-based index of the current page
	Total        int              // Total number of pagination pages
	HasPrev      bool
	HasNext      bool
	PrevURL      string
	NextURL      string
	TotalItems   int    // Total content items across all pagers
	BaseURL      string // Collection base URL for constructing custom pagination links
	FirstURL     string // Permalink to the first pagination page
	LastURL      string // Permalink to the last pagination page
}

type PhaseTiming struct {
	Phase    string
	Duration time.Duration
}

type PrevNextConfig struct {
	Enabled bool
	Labels  [2]string
}

type RenderResult struct {
	HTML          string
	Headings      []Heading
	HasCodeBlocks bool
	HasImages     bool
	Links         []CollectedLink
}

type Resource struct {
	Name         string
	Title        string
	MediaType    string
	RelPermalink string
	Width        int
	Height       int
	SrcPath      string // absolute filesystem path for image processing
}

type RouteAssets struct {
	Scripts       []string
	Styles        []string
	InlineScripts []template.JS
	ModuleScripts []string
}

type RouteData struct {
	Page       *Page
	Collection *Collection
	Site       *SiteContext
	Theme      *ThemeConfig
	Layout     LayoutType
	Template   string

	RouteNav
	RouteI18n
	RouteVersioning
	RouteTabs
	RouteAssets

	Homepage     *HomepageData
	Taxonomy     *Taxonomy
	TaxonomyTerm *TaxonomyTerm
	TermEntries  []*TermEntry
	PageBanner   *PageBanner
}

type RouteI18n struct {
	Lang            string
	Dir             string
	Translations    []TranslationLink
	AllTranslations []TranslationLink
}

type RouteNav struct {
	GlobalNav                 *GlobalNav
	Sidebar                   *NavTree
	SidebarType               string
	Breadcrumbs               []BreadcrumbItem
	Pagination                *PaginationLinks
	Paginator                 *Paginator
	HasSidebar                bool
	SidebarCollapsedByDefault bool
	Section                   *Section
	IsSection                 bool
}

type RouteTabs struct {
	IsTabbed  bool
	DocsTabs  []*DocsTab
	ActiveTab *DocsTab
}

type RouteVersioning struct {
	Version       string
	VersionLabel  string
	Versions      []VersionLink
	IsLatest      bool
	VersionBanner string
}

type Section struct {
	Title       string
	Slug        string
	Permalink   string
	Pages       []*Page
	Sections    []*Section
	IndexPage   *Page
	Parent      *Section
	Collection  *Collection
	Transparent bool
	Render      bool
}

type SidebarConfig struct {
	Collapsible        bool
	CollapsedByDefault bool
	MaxDepth           int
	Search             bool
}

type SiteContext struct {
	Title            string
	BaseURL          string
	BasePath         string // normalized: "/docs/" or "/"
	Language         string
	Generator        string
	Favicon          string
	FaviconType      string
	SitemapEnabled   bool
	Config           any // *config.SiteConfig at runtime; any to avoid circular imports
	Collections      map[string]*Collection
	Taxonomies       map[string]*Taxonomy
	TaxonomiesByLang map[string]map[string]*Taxonomy
	Pages            []*Page
	Data             map[string]any
	BuildTime        time.Time
	Languages        []Language
	DefaultLang      string
	EditURL          string        // base URL for "edit this page" links (e.g. https://github.com/user/repo/edit/main/content)
	KazariScriptURL  string        // URL of the Kazari interaction JS file served globally on every page
	IconLicenses     []IconLicense // license metadata for loaded icon sets (for an attribution/credits page)
}

type TOCConfig struct {
	Enabled         bool
	MinLevel        int
	MaxLevel        int
	ScrollHighlight bool
}

type Taxonomy struct {
	Name       string
	Singular   string
	Terms      map[string]*TaxonomyTerm
	Permalink  string
	PaginateBy int // 0 = no pagination for term listing pages
}

type TaxonomyTerm struct {
	Name        string
	Slug        string
	CustomSlug  string // from permalink field in data/*.yml; overrides Slugify(Name)
	Permalink   string
	Pages       []*Page
	Label       string
	Description string
	Color       string
	Icon        string
	Hidden      bool
	Priority    int
	Difficulty  string // beginner, intermediate, advanced
	ContentType string // lecture, lab, assignment, project, reference, tutorial, assessment
}

type TermEntry struct {
	*TaxonomyTerm
	Count   int
	PopTier int // 1-5 popularity quintile
}

type ThemeConfig struct {
	Name        string
	Slug        string
	Version     string
	Author      string
	Tokens      map[string]string
	DarkTokens  map[string]string
	DarkEnabled bool
	StyleTag    template.HTML // pre-rendered <style> block with :root/:root[data-theme="dark"] tokens
}

type ThemeResolver struct {
	ProjectDir string // root of user project (contains layouts/, themes/)
	ThemeName  string // active theme name (for themes/<name>/layouts/)
	EmbeddedFS fs.FS  // compiled-in embedded/theme/ filesystem
}

type TranslationLink struct {
	Lang       string
	Name       string // display name (e.g. "Français"), falls back to Lang code
	Dir        string // "ltr" or "rtl"
	URL        string
	Title      string
	IsFallback bool
}

type URLResolver struct {
	BasePath    string // normalized: "/docs/" or "/"
	BaseURL     string // origin only: "https://example.com"
	I18nEnabled bool
	DefaultLang string
	Strategy    string          // "prefix-except-default"
	Languages   map[string]bool // set of known language codes

	CollectionMounts []string        // ["/docs", "/blog"] — populated by builder
	VersionIDs       map[string]bool // union of all version IDs across versioned collections
}

type ValidationEntry struct {
	Links    []CollectedLink
	FilePath string
}

type ValidationWarning struct {
	File    string
	Field   string
	Message string
	Level   string
}

type VersionConfig struct {
	Enabled                   bool
	LastVersion               string // version ID that serves the root URL (no prefix)
	PublishLatestAtVersionURL bool
	Versions                  []VersionDef
}

type VersionDef struct {
	ID       string
	Label    string
	Path     string // URL path segment (defaults to ID)
	Banner   string // "none" / "unmaintained" / "unreleased"
	Redirect string // "same-page" / "root"
}

type VersionLink struct {
	ID        string
	Label     string
	URL       string // target URL (peer page or version root, based on redirect strategy)
	Title     string
	IsCurrent bool
	IsLatest  bool   // true if this is the last_version
	Banner    string // "none" / "unmaintained" / "unreleased"
	Redirect  string // "same-page" / "root"
}