plugin

type ExportFailure struct {
	Item ExportItem
	Err  string
}

type ExportItem struct {
	// Path is the output file path relative to the project root.
	Path string
	// Lang is "zh" or "en".
	Lang string
	// Format is "epub", "pdf", or "docx".
	Format string
	// Slug of the source book/practice (empty for complete collections).
	Slug string
}

type ExportRequest struct {
	// SourceDir is the project root containing huan.yaml and content/.
	SourceDir string

	// Type filters content: "books", "practices", "all".
	Type string

	// Format filters output: "epub", "pdf", "docx", "all".
	Format string

	// Level filters granularity: "individual", "volumes", "complete", "all".
	// ("volumes" and "seasons" are aliases; normalized here to "volumes".)
	Level string

	// Slug restricts to a single book/practice slug (optional).
	Slug string

	// Volume restricts to one volume/season number, 1-based (optional; 0 = all).
	Volume int

	// Force regenerates even when the manifest hash matches.
	Force bool

	// Jobs is the parallelism for per-book generation. 0 = runtime.NumCPU()-1.
	Jobs int
}

type ExportResult struct {
	Succeeded []ExportItem
	Failed    []ExportFailure
	// Skipped lists items skipped by the incremental manifest (hash match).
	Skipped []ExportItem
	// Warnings carries non-fatal notes (e.g. missing .en.md sidecars).
	Warnings []string
}

type Exporter interface {
	Plugin

	// Export runs the ebook generation batch. Implementations should:
	//   - Honor ctx for cancellation.
	//   - Return a Result with per-item Succeeded/Failed/Skipped lists even on
	//     partial failure (collection-not-interruption).
	//   - Return a non-nil error only when the export cannot proceed at all
	//     (invalid request, missing content root, missing CJK font for pdf).
	Export(ctx context.Context, req ExportRequest) (ExportResult, error)
}

type FieldSchema struct {
	Key         string // 字段名，对应 yaml key
	Type        string // "string" | "int" | "bool" | "string_slice" | "map"
	Required    bool   // true = 必填，启动时校验
	Default     any    // 默认值（Required=false 时生效）
	Description string // 人类可读的说明
	Sensitive   bool   // true = 在 CLI info 中 mask 为 ***
	EnvVarHint  string // 建议的环境变量名，仅用于文档提示
}

type MetadataProvider interface {
	PluginMetadata() PluginMeta
}

type Plugin interface {
	// Name is the plugin's unique identifier. It matches the yaml key under
	// plugins: (e.g. Name()=="seo_injector" pairs with yaml plugins.seo_injector.*).
	Name() string
}

type PluginMeta struct {
	Version    string   `json:"version"`
	Author     string   `json:"author"`
	RepoURL    string   `json:"repoURL"`
	License    string   `json:"license"`
	Tags       []string `json:"tags"`
	IsOfficial bool     `json:"isOfficial"`
}

type PostBuildHook interface {
	Plugin

	// OnOutputWritten is called after all output files are written, before the
	// build result is finalized. Receives the output directory for
	// post-processing (e.g. inject SEO meta, enhance sitemap, inject HTML).
	// Collection-not-interruption: a returned error logs a warning and does
	// not abort the build.
	OnOutputWritten(ctx context.Context, outputDir string) error
}

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

type Schema struct {
	Fields []FieldSchema
}

type SchemaProvider interface {
	ConfigSchema() Schema
}

type ShortcodeContext struct {
	Params map[string]string
	Inner  string
}

type ShortcodeHandler func(ctx ShortcodeContext) (string, error)

type ShortcodeProvider interface {
	Shortcodes() map[string]ShortcodeHandler
}

type TemplateEntry struct {
	Path    string // Logical path, e.g. "index.html"
	Content string // Template content
}

type ThemeHooks interface {
	BeforeRender(ctx context.Context) error
	AfterRender(ctx context.Context) error
}

type ThemeInfo struct {
	Name        string   `json:"name"`
	Version     string   `json:"version"`
	Author      string   `json:"author"`
	Description string   `json:"description"`
	Screenshot  string   `json:"screenshot,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	MinHuanVer  string   `json:"minHuanVer,omitempty"`
}

type ThemePlugin interface {
	Plugin

	// Info returns the theme's metadata as a key-value map.
	Info() map[string]any

	// Templates returns the list of templates the theme provides.
	// Each entry has "path" and "content" keys.
	Templates() []map[string]string

	// FuncMap returns the theme's custom template functions.
	FuncMap() template.FuncMap

	// Assets returns the theme's static asset filesystem.
	Assets() fs.FS
}