render

type Address struct {
	Street     string `json:"street"`
	City       string `json:"city"`
	State      string `json:"state"`
	PostalCode string `json:"postal_code"`
	Country    string `json:"country"`
}

type AttrCount struct {
	Value string
	Count int
}

type AuthorLink struct{ Label, URL string }

type AuthorView struct {
	Name, Slug, URL, Avatar string
	// Bio is the author's short biography ("" when none).
	Bio string
	// JobTitle is the person's role ("" when none).
	JobTitle string
	// IsOrg is true for a byline that credits the site organisation: Name is
	// the site name and there is no URL.
	IsOrg bool
	// SameAs are the person's public profile links (website, LinkedIn, ...).
	SameAs []string
	// Links are the same links with a visible label ("LinkedIn", "X", ...).
	Links []AuthorLink
}

type Chain []fs.FS

type Crumb struct {
	Name string
	URL  string
}

type DataSource interface {
	Recent(schema string, limit int) []RelatedItem
	Terms(kind string, limit int) []TermView
	Menu(location string) []NavItem
	// ImageVariants returns the resized copies of a local media URL, widest last.
	ImageVariants(url string) []ImageVariant
	// Query lists published entities matching q (see QuerySpec); the spec the
	// funcs pass is already clamped.
	Query(q QuerySpec) QueryResult
	// AttrValues lists the distinct non-empty string values of an attribute of
	// a schema's published entities, sorted by value.
	AttrValues(schema, attr string, limit int) []AttrCount
}

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

type DocBody struct {
	HTML template.HTML
	TOC  []TOCItem
}

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

type EntityView struct {
	ID, Title, Slug, URL, Schema string
	// Excerpt and Image are the first of the common attribute spellings.
	Excerpt, Image string
	// Attributes is a read-only copy of the stored attributes (page_sections omitted).
	Attributes  map[string]any
	Terms       []TermView
	Author      *AuthorView
	PublishedAt time.Time
	UpdatedAt   time.Time
}

type ExtBatch struct {
	Path, Language, SchemaSlug, EntityID string
	Requests                             []ExtRequest
}

type ExtRequest struct {
	ID, Source string
	Limit      int
}

type ExtResult struct {
	Value string
	Items []RelatedItem
	OK    bool
}

type ExtSourceFunc func(ctx context.Context, b ExtBatch) map[string]ExtResult

type FeedLink struct {
	Title, Type, Href string
}

type FormField struct {
	Name        string
	Label       string
	Type        string // text|email|tel|textarea|select|checkbox|radio
	Required    bool
	Placeholder string
	HelpText    string
	Options     []FormOption
}

type FormOption struct {
	Value string
	Label string
}

type FormView struct {
	Slug          string
	Name          string
	Fields        []FormField
	SubmitLabel   string
	SuccessNotice string
	// Captcha asks for a spam-check widget above the submit button. It is set
	// only when the form requires the check and a provider is usable.
	// CaptchaSiteKey is public by design; the secret never reaches a view.
	Captcha         bool
	CaptchaProvider string // turnstile|recaptcha|hcaptcha
	CaptchaSiteKey  string
}

type Fragment struct {
	Sel  string            `json:"sel"` // "section" | "node"
	Key  string            `json:"key"`
	HTML string            `json:"html"`
	CSS  map[string]string `json:"css,omitempty"`
}

type HeadContext struct {
	Path       string
	Language   string
	SchemaSlug string
	EntityID   string
	Tags       []HeadTag
	// ReplaceSiteGraph asks the host to omit its generic Organization/WebSite
	// graph because the filter supplies its own as jsonld tags.
	ReplaceSiteGraph bool
}

type HeadFilter func(ctx context.Context, c HeadContext) HeadContext

type HeadTag struct {
	// Kind is meta, link, script-src or jsonld.
	Kind string
	// Attrs are the tag attributes; names outside the per-kind allowlist are dropped.
	Attrs map[string]string
	// JSONLD is the document for Kind "jsonld".
	JSONLD []byte
}

type ImageSizer interface {
	ImageSize(url string) (w, h int, ok bool)
}

type ImageVariant struct {
	URL   string
	Width int
}

type Link struct {
	Label string
	URL   string
}

type NavItem struct {
	Label    string
	Href     string
	Target   string
	Children []NavItem
}

type NavPosition struct {
	Trail      []NavItem // ancestors, root first, excluding the current item
	Current    *NavItem
	Prev, Next *NavItem // depth-first neighbours that have an Href
}

type Options struct {
	// Layers are theme file systems layered over the embedded default, highest
	// precedence first. The server passes the active theme package (loaded from
	// Postgres); none means the built-in default theme alone.
	Layers []fs.FS
	// Settings are the active theme's settings values, exposed to templates as
	// .Settings (see SetSettings).
	Settings map[string]any
	// HeadFilter optionally lets plugins add head tags (fail-open).
	HeadFilter HeadFilter
	// Data feeds the recent, terms, menu and srcset template funcs (optional).
	Data DataSource
	// ThemeName names the theme in boot fault identifiers (see SetThemeName).
	ThemeName string
	// Refs resolves ref nodes (synced blocks) and theme parts. Without it a ref
	// renders as a missing block.
	Refs RefSource
	// ExtSources resolves plugin data sources for ext.* bindings and source
	// loops, one batch per render (nil: no external data).
	ExtSources ExtSourceFunc
	// Logger receives rebuild and plugin partial diagnostics (default slog.Default()).
	Logger *slog.Logger
}

type PackFiles struct {
	HTML, CSS, Island []byte
}

type PackWidget struct {
	Kind              string
	HTML, CSS, Island []byte
}

type PageLink struct {
	N       int
	URL     string
	Current bool
	// Gap marks an ellipsis between non-adjacent pages (N and URL are empty).
	Gap bool
}

type PageMeta struct {
	Name         string
	Title        string
	Description  string
	OGImage      string
	OGType       string
	CanonicalURL string
	NoIndex      bool
}

type PageView struct {
	// Ctx is the request context, used only so render failures are logged with
	// it (the smoke check attributes errors by it). Nil means no request.
	Ctx context.Context
	// Kind selects the template hierarchy (see layoutCandidates). Empty means
	// KindSingle for an entity page (EntityID set) and KindPage otherwise.
	Kind string
	// Entity is the entity behind a single or home view; nil elsewhere.
	Entity *EntityView
	// Items and Pagination are set on archive, taxonomy, author and search views.
	Items      []RelatedItem
	Pagination *Pagination
	// Term is set on taxonomy views, Author on author views, Query on search views.
	Term   *TermView
	Author *AuthorView
	Query  string
	// SearchType is the schema slug a search is limited to ("" for the whole site).
	SearchType string
	// Dynamic marks a view built from per-request data (taxonomy, author,
	// search) that no entity event invalidates: the server never caches it.
	Dynamic  bool
	Site     SiteView
	Page     PageMeta
	Sections []Section
	// Doc is a page_doc v2 tree. When set it replaces Sections: v1-shaped nodes
	// render through the theme section partial, the rest natively.
	Doc *builder.Doc

	BaseURL    string
	Path       string
	Breadcrumb []Crumb
	// JSONLD holds backend-built JSON-LD documents, emitted verbatim (escaped).
	JSONLD []json.RawMessage
	// AICrawlerComment is an optional HTML comment body for AI crawlers.
	AICrawlerComment string
	EntityID         string
	SchemaSlug       string
	// Attrs is a read-only copy of the entity's attributes (page_sections
	// omitted; it is in Sections). Numbers are float64. Entity pages only. Treat strings as
	// plain text: html/template escapes them; use sanitisedHTML for rich text.
	Attrs map[string]any
	// EntityLinks maps the data-entity-id of internal links in the page content to
	// the target's current public path. RewriteEntityLinks applies it at render so
	// links survive slug changes; ids missing from the map keep their stored href.
	EntityLinks map[string]string
	// PageNum is the request's ?page= (1..MaxQueryPage, 0 reads as 1); the
	// pageNum func reads it on every view.
	PageNum int
	// Params is the request's query string; the queryParam func reads it on
	// every view. Pages with a query string are never page-cached.
	Params url.Values
	// Related lists up to limit (clamped to 1..12) other published entities of
	// the page's schema, newest first, excluding the page itself. Lazy: the
	// query only runs when a layout calls it ({{range call .Related 3}}). Never
	// nil in a layout (a no-op returning nil on archive, 404, error and
	// unsaved-preview views, and when nothing is found).
	Related func(limit int) []RelatedItem
	// Series returns the editorial series the entity belongs to
	// (attributes.series_slug): its published and scheduled parts in part
	// order, or nil when the entity has no series or it has no parts. Lazy and memoised per
	// render ({{with call .Series}}...{{end}}). Never nil in a layout.
	Series func() *SeriesView
	// PostsByAuthor lists a page of the published posts written by this
	// team-member entity, newest first. limit is clamped to 1..50 and page to
	// >= 1 (pass .PageNum). Lazy and memoised per (limit, page). Never nil in a
	// layout: a zero PostsPage on any other entity.
	PostsByAuthor func(limit, page int) PostsPage
	// Uncacheable, when non-nil, is set during rendering if a lazy data source
	// (Related) failed, so the caller serves the page but does not cache it.
	Uncacheable *bool
	// PagedLoop and LoopOutOfRange, when non-nil, are set during rendering when
	// the page has a paged builder loop and when the requested ?page= is past
	// its last page. The server caches ?page=N only for the former and answers
	// 404 for the latter.
	PagedLoop, LoopOutOfRange *bool
	// PublishedAt and UpdatedAt are zero when unknown.
	PublishedAt time.Time
	UpdatedAt   time.Time
	// Forms is keyed by form slug, filled for each contact_form section.
	Forms map[string]FormView
	// PluginDirectory feeds plugin_directory sections; nil when the page has
	// none.
	PluginDirectory *PluginDirectoryView
	// ThemeDirectory feeds theme_directory sections; nil when the page has
	// none.
	ThemeDirectory *ThemeDirectoryView
	// MaxCacheAge, when > 0, caps how long the rendered page may be cached,
	// whatever the configured page cache TTL.
	MaxCacheAge time.Duration
	// Preview marks an unsaved-draft render (noindex, data-hm-preview).
	Preview bool
	// Canvas marks an admin canvas render: html-kind bodies carry data-hm-text
	// editor markers (see canvas_text.go).
	Canvas bool
	// NoParts turns the theme parts off for this render: the canvas of a part
	// itself, so the assigned part is not drawn twice.
	NoParts bool
	// Submitted is set after a no-JS form post redirect (?submitted=1).
	Submitted bool
	// FormError is set after a failed no-JS form post redirect (?form_error=1).
	FormError bool
	// contains filtered or unexported fields
}

type Pagination struct {
	Page, PerPage, Total, TotalPages int
	HasPrev, HasNext                 bool
	PrevURL, NextURL                 string
	// Path and Query (the other, already encoded parameters) build page URLs.
	Path  string
	Query string
}

type PermLine struct {
	Name, Text string
	Warn       bool
}

type PluginCard struct {
	Name, Title, Version, Tier, TierLabel, Author, Description, Source string
	PermCount                                                          int
	PermWarn                                                           []string
	PermLines                                                          []PermLine
	// Permissions lists the raw permission names. The default theme no longer
	// reads it; it is kept for theme overrides written against older cores.
	Permissions []string
	Search      string
}

type PluginDirectoryView struct {
	State string
	Cards []PluginCard
}

type PostsPage struct {
	Items []RelatedItem
	// Total counts every matching post; Page is the page served; Pages is the
	// page count (at least 1).
	Total, Page, Pages int
}

type QueryResult struct {
	Items                     []RelatedItem
	Total, Page, Pages, Limit int
}

type QuerySpec struct {
	// Schema is the schema slug (aliases are included by the implementation).
	Schema string
	// Attr and Eq filter on attributes[Attr] == Eq; Attr alone requires the
	// attribute to exist. EqSet says Eq was given (an empty Eq then matches
	// the empty string, not "exists").
	Attr, Eq string
	EqSet    bool
	// IncludeScheduled adds scheduled entities (their date, no URL).
	IncludeScheduled bool
	// Author is an author slug, Term a "<kind>:<slug>" taxonomy term. A slug
	// that names nothing gives no items.
	Author, Term string
	// Order is "-published_at" (default), "published_at", "name", "-name",
	// "attr:<key>" or "-attr:<key>".
	Order string
	// Limit is 1..MaxQueryLimit and Page 1..MaxQueryPage.
	Limit, Page int
	// Offset skips this many items before the first page (0..1000).
	Offset int
	// ExcludeID is the uuid (text) of an entity to leave out; an invalid
	// value is ignored.
	ExcludeID string
}

type RefSource interface {
	// Block returns the doc of a block entity. It is false for an unknown id
	// and for an entity that is not a block (a page id, a part id); the status
	// does not matter, blocks are always drafts.
	Block(ctx context.Context, id string) (*builder.Doc, bool)
	// Part returns the doc of a theme_part entity whose slot is slot.
	Part(ctx context.Context, slot, id string) (*builder.Doc, bool)
}

type RelatedItem struct {
	Title, URL, Excerpt, Image, Category string
	// Name is the entity's own name (Title is attributes.title, else Name).
	Name string
	// Schema is the slug of the entity's schema.
	Schema      string
	PublishedAt time.Time
	// UpdatedAt is zero for scheduled items.
	UpdatedAt time.Time
	// Author and AuthorURL are empty when the entity has no named author.
	Author, AuthorURL string
	// WordCount is the number of words of the entity's attributes.content and
	// ReadingTime the minutes to read it, both as the readingTime func counts
	// (0 when there is no content).
	WordCount, ReadingTime int
	// Attrs is a read-only copy of the entity's attributes without
	// page_sections and content (the body would make every card heavy). Numbers
	// are float64; strings are plain text that html/template escapes.
	Attrs map[string]any
}

type Section struct {
	ID        string
	Type      string
	Title     string
	Content   map[string]any
	IsVisible *bool
	SortOrder int
}

type SectionDef struct {
	Type string
	// Template is the html/template source of sections/<type>.html.
	Template string
	// Schema is the raw JSON Schema of schemas/<type>.json (nil if absent).
	Schema json.RawMessage
	// Meta is the schema's x-hm-section extension.
	Meta SectionMeta
	// Aliases maps a canonical top-level field to its legacy names (x-hm-alias).
	Aliases map[string][]string
	// FieldKinds maps a top-level field to its x-hm-field kind.
	FieldKinds map[string]string
}

type SectionInfo struct {
	Type        string          `json:"type"`
	Title       string          `json:"title"`
	Description string          `json:"description,omitempty"`
	Schema      json.RawMessage `json:"schema,omitempty"`
}

type SectionMeta struct {
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Icon        string `json:"icon,omitempty"`
}

type SeriesPartView struct {
	Title, URL  string
	Part        int
	Index       bool
	Published   bool
	PublishDate time.Time
}

type SeriesView struct {
	Slug, Name string
	// Total is the number of numbered parts (the index page is not one).
	Total    int
	IndexURL string
	// Parts is ordered by Part; the index page has Part 0 and Index true.
	// IndexURL is empty until the index page is published.
	Parts []SeriesPartView
}

type SiteView struct {
	Name        string
	Tagline     string
	LogoURL     string
	Nav         []NavItem
	FooterNav   []NavItem
	SocialLinks []Link
	// HeaderCTA is the optional header button; nil renders none.
	HeaderCTA *Link
	// Feeds are the site's syndication feeds, advertised in the head as
	// <link rel="alternate">. Empty when the site has none.
	Feeds  []FeedLink
	Tokens ThemeTokens
	// Language is the BCP 47 site language (default "en" when unset).
	Language string
	// Phone, Hours and Address are the public contact details from the site
	// settings; empty when unset. They also feed the Organization JSON-LD.
	Phone, Hours string
	Address      Address
	// Settings are the site's theme settings (theme_config extras), read-only.
	Settings map[string]any
	// Design is the site design system (tokens and style presets) read from the
	// theme settings; the zero value means none.
	Design builder.Design
}

type TOCItem struct {
	ID, Text string
	Level    int // 2 or 3
}

type TermView struct {
	Kind, Slug, Name, URL string
	Count                 int
	Description, Parent   string
}

type TextNode struct {
	Index int    `json:"index"`
	Tag   string `json:"tag"` // parent element name
	Text  string `json:"text"`
}

type Theme struct {
	Name    string
	Version string
	// Settings is the raw settings_schema from theme.json (may be nil).
	Settings json.RawMessage
	// Sections is keyed by section type, discovered from the file layout.
	Sections map[string]*SectionDef

	// BuilderTokens is the theme's opt-in (theme.json "builder": {"tokens": true})
	// to the site design tokens: the :root token block and the --hm-fs-* type
	// scale variables. Without it the builder emits neither.
	BuilderTokens bool
	// BuilderParts are the layout slots (header, footer, single, archive) the
	// theme lets the owner fill with a part built in the builder
	// (theme.json builder.parts); nil when it did not opt in.
	BuilderParts map[string]bool
	// StrictScripts is the theme's opt-in (theme.json "csp": {"strictScripts": true})
	// to the public policy without 'unsafe-inline' in script-src. It promises the
	// theme emits no inline executable script and no on*= handler on public pages.
	StrictScripts bool
	// contains filtered or unexported fields
}

type ThemeCard struct {
	Name, Title, Version, Description, Source, Screenshot, Tier, TierLabel, Author, Search string
}

type ThemeDirectoryView struct {
	State string
	Cards []ThemeCard
}

type ThemeInfo struct {
	Name           string          `json:"name"`
	Version        string          `json:"version"`
	Sections       []SectionInfo   `json:"sections"`
	SettingsSchema json.RawMessage `json:"settings_schema,omitempty"`
}

type ThemeTokens struct {
	Primary, Background, Text    string
	Font, FontHeading            string
	RadiusSm, RadiusMd, RadiusLg string
}

type VariantPrefetcher interface {
	PrefetchVariants(urls []string)
}