tinkerdown

type Action struct {
	Kind      string              `yaml:"kind"`                // Action kind: "sql", "http", "exec"
	Source    string              `yaml:"source,omitempty"`    // For sql: source name to execute against
	Statement string              `yaml:"statement,omitempty"` // For sql: SQL statement with :param placeholders
	URL       string              `yaml:"url,omitempty"`       // For http: request URL (supports template expressions)
	Method    string              `yaml:"method,omitempty"`    // For http: HTTP method (default: POST)
	Body      string              `yaml:"body,omitempty"`      // For http: request body template
	Cmd       string              `yaml:"cmd,omitempty"`       // For exec: command to run
	Params    map[string]ParamDef `yaml:"params,omitempty"`    // Parameter definitions
	Confirm   string              `yaml:"confirm,omitempty"`   // Confirmation message (triggers dialog)
}

type BlocksConfig struct {
	AutoID          bool   `yaml:"auto_id"`
	IDFormat        string `yaml:"id_format"`
	ShowLineNumbers bool   `yaml:"show_line_numbers"`
}

type ChartOptions struct {
	Colors     []string `yaml:"colors,omitempty" json:"colors,omitempty"`
	Stacked    bool     `yaml:"stacked,omitempty" json:"stacked,omitempty"`
	Horizontal bool     `yaml:"horizontal,omitempty" json:"horizontal,omitempty"`
	Legend     *bool    `yaml:"legend,omitempty" json:"legend,omitempty"`
}

type CodeBlock struct {
	Type     string            // "server", "wasm", "lvt"
	Language string            // "go", etc.
	Flags    []string          // "readonly", "editable"
	Metadata map[string]string // id, state, etc.
	Content  string
	Line     int // Line number in source file
}

type DiagramRenderer interface {
	Render(source []byte) ([]byte, error)
}

type EmbedRoute struct {
	Path     string
	Upstream string
}

type FeaturesConfig struct {
	HotReload bool `yaml:"hot_reload"`
	Sidebar   bool `yaml:"sidebar"` // Show navigation sidebar
}

type Frontmatter struct {
	// Page metadata
	Title       string      `yaml:"title"`
	Description string      `yaml:"description,omitempty"` // Used for <meta name="description"> + og:description
	Image       string      `yaml:"image,omitempty"`       // Path/URL used for og:image (falls back to site logo)
	Type        string      `yaml:"type"`                  // tutorial, guide, reference, playground
	Persist     PersistMode `yaml:"persist"`               // none, localstorage, server
	Steps       int         `yaml:"steps"`

	// Top-level convenience options
	Sidebar *bool `yaml:"sidebar,omitempty"` // Show navigation sidebar (overrides features.sidebar)

	// Layout selects the page shell. "" or "docs" (default) renders the full
	// docs chrome (sidebar, breadcrumbs, opinionated typography). "landing"
	// renders a minimal full-bleed shell for bespoke marketing pages — no
	// sidebar, no content-wrapper clamp, no docs typography — while still
	// loading the client JS (so embed-lvt demos work) and any styling.custom_css.
	// Unknown values fall back to the docs layout.
	Layout string `yaml:"layout,omitempty"`

	// LvtShowSource toggles the page-level default for ` “`lvt ` block source
	// display. When true, every ` “`lvt ` block on the page renders both its
	// template source as a syntax-highlighted code listing AND the live
	// interactive widget. Per-block `show-source` / `hide-source` flags
	// override this default. Defaults to nil/false to preserve existing
	// behavior — opt-in for documentation pages.
	LvtShowSource *bool `yaml:"lvt_show_source,omitempty"`

	// Source provenance — used to render an "Edit this page" link that
	// points at the canonical source file in its origin repo. Useful when
	// a page was synced from another repo and the docs site is not the
	// canonical home of the content. Both default to "" (use site-level
	// repository + the page's own relative path).
	SourceRepo string `yaml:"source_repo,omitempty"` // e.g. "https://github.com/livetemplate/livetemplate"
	SourcePath string `yaml:"source_path,omitempty"` // e.g. "docs/guides/progressive-complexity.md"
	// SourceRef pins the git ref used in include source-link footers
	// (tag/branch/commit). Resolution order: this field if set;
	// otherwise tinkerdown.DefaultSourceRef (populated from the
	// binary's release version by cmd/tinkerdown/main.go); otherwise
	// "main".
	SourceRef string `yaml:"source_ref,omitempty"`
	// SourceCommit records the exact upstream commit at sync time. It is
	// displayed as provenance in site chrome when present.
	SourceCommit string `yaml:"source_commit,omitempty"`

	// Chart customization (keyed by heading slug)
	Charts map[string]ChartOptions `yaml:"charts,omitempty"`

	// Config options (can override livemdtools.yaml)
	Sources  map[string]SourceConfig `yaml:"sources,omitempty"`
	Actions  map[string]Action       `yaml:"actions,omitempty"`
	Styling  *StylingConfig          `yaml:"styling,omitempty"`
	Blocks   *BlocksConfig           `yaml:"blocks,omitempty"`
	Features *FeaturesConfig         `yaml:"features,omitempty"`

	// Computed expressions found in the markdown content (populated during parsing)
	// Map of expression ID to expression string (e.g., "expr-1" -> "count(tasks where done)")
	Expressions map[string]string `yaml:"-"`

	// Schedule tokens found in the markdown content (populated during parsing)
	Schedules []*schedule.Token `yaml:"-"`

	// Imperative commands (Notify, Run action) found in the markdown (populated during parsing)
	Imperatives []*schedule.Imperative `yaml:"-"`

	// Schedule parsing warnings (populated during parsing)
	ScheduleWarnings []schedule.ParseWarning `yaml:"-"`

	// HasCharts indicates the page has {chart:...} annotations (populated during parsing)
	HasCharts bool `yaml:"-"`

	// HasMermaid indicates the page has “`mermaid fenced blocks (populated during parsing)
	HasMermaid bool `yaml:"-"`
}

type InteractiveBlock struct {
	ID       string
	StateRef string // References a ServerBlock ID
	Template *livetemplate.Template
	Store    interface{} // State object with action methods (uses method dispatch)
	Content  string      // Template content
	Metadata map[string]string
}

type MessageEnvelope struct {
	BlockID string          `json:"blockID"`
	Action  string          `json:"action"`
	Data    json.RawMessage `json:"data"`
}

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

type Page struct {
	ID                string
	Title             string
	Description       string // From frontmatter; used for <meta description> + og:description
	Image             string // From frontmatter; used for og:image
	Type              string // tutorial, guide, reference, playground
	SourceFile        string // Absolute path to source .md file (for error messages)
	SourceRepo        string // Origin GitHub repo URL from frontmatter (for edit link)
	SourcePath        string // Path within origin repo from frontmatter (for edit link)
	SourceRef         string // Git ref from frontmatter, when known
	SourceCommit      string // Immutable source commit from frontmatter, when known
	Sidebar           *bool  // nil = use default, true/false = explicit override
	Layout            string // From frontmatter; "" / "docs" = default shell, "landing" = minimal full-bleed shell
	Config            PageConfig
	StaticHTML        string
	ServerBlocks      map[string]*ServerBlock
	WasmBlocks        map[string]*WasmBlock
	InteractiveBlocks map[string]*InteractiveBlock
	// Expressions maps expression IDs to expression strings (e.g., "expr-0" -> "count(tasks where done)")
	// These are computed expressions found in inline code spans like `=count(tasks where done)`
	Expressions map[string]string

	// Schedules contains parsed schedule tokens found in the markdown content
	Schedules []*schedule.Token

	// Imperatives contains parsed imperative commands (Notify, Run action) from the markdown
	Imperatives []*schedule.Imperative

	// ScheduleWarnings contains any warnings generated during schedule parsing
	ScheduleWarnings []schedule.ParseWarning

	// HasCharts indicates the page has chart annotations requiring Chart.js
	HasCharts bool

	// HasMermaid indicates the page contains “`mermaid fenced blocks
	// requiring the Mermaid runtime (~3.3MB). Used by the server to
	// conditionally inject the script and avoid penalising pages without
	// any diagrams.
	HasMermaid bool

	// EmbedRoutes is the set of (path, upstream) pairs declared by
	// ` “`embed-lvt path="..." upstream="..." ` blocks on this page.
	// The server walks every page after Discover() and turns these into
	// auto-registered reverse-proxy routes, so authors don't have to
	// duplicate the upstream coordinates in tinkerdown.yaml.
	EmbedRoutes []EmbedRoute

	// IncludedFiles holds the absolute paths of files referenced by
	// ` “`LANG include="..." ` fences on this page. The watcher uses
	// this list to broadcast a reload when any included file changes,
	// so docs stay in sync with the real source they cite.
	IncludedFiles []string
}

type PageConfig struct {
	// Page behavior
	Persist   PersistMode
	MultiStep bool
	StepCount int

	// Effective config (merged from frontmatter + site config)
	Sources  map[string]SourceConfig
	Actions  map[string]Action
	Styling  StylingConfig
	Blocks   BlocksConfig
	Features FeaturesConfig
}

type PageState struct {

	// Current step for multi-step tutorials
	CurrentStep int

	// Interactive block states (stored as generic interfaces)
	// State objects use method dispatch for action handling
	InteractiveStates map[string]interface{}

	// Code edits for WASM blocks (blockID -> code)
	CodeEdits map[string]string

	// Completed steps tracking
	CompletedSteps []int
	// contains filtered or unexported fields
}

type ParamDef struct {
	Type     string `yaml:"type,omitempty"`     // Parameter type: "string", "number", "date", "bool"
	Required bool   `yaml:"required,omitempty"` // Whether the parameter is required
	Default  string `yaml:"default,omitempty"`  // Default value
}

type ParseError struct {
	File    string // Source file path
	Line    int    // Line number (1-indexed)
	Column  int    // Column number (1-indexed, optional)
	Message string // Error message
	Code    string // Offending code snippet
	Hint    string // Helpful suggestion
	Related string // Related information (e.g., "State 'foo' defined at line 20")
}

type PersistMode string

type ResponseEnvelope struct {
	BlockID string                 `json:"blockID"`
	Tree    map[string]interface{} `json:"tree,omitempty"`
	Meta    map[string]interface{} `json:"meta"`
}

type ServerBlock struct {
	ID       string
	Language string // Currently only "go"
	Content  string
	Metadata map[string]string
}

type SourceConfig struct {
	Type        string                 `yaml:"type"`                   // exec, pg, rest, csv, json, markdown, sqlite, wasm
	Cmd         string                 `yaml:"cmd,omitempty"`          // For exec type
	Query       string                 `yaml:"query,omitempty"`        // For pg type
	From        string                 `yaml:"from,omitempty"`         // For rest type: API endpoint URL
	File        string                 `yaml:"file,omitempty"`         // For csv/json/markdown types
	Anchor      string                 `yaml:"anchor,omitempty"`       // For markdown: section anchor (e.g., "#todos")
	DB          string                 `yaml:"db,omitempty"`           // For sqlite: database file path
	Table       string                 `yaml:"table,omitempty"`        // For sqlite: table name
	Path        string                 `yaml:"path,omitempty"`         // For wasm: path to .wasm file
	QueryFile   string                 `yaml:"query_file,omitempty"`   // For graphql: path to .graphql file
	Variables   map[string]interface{} `yaml:"variables,omitempty"`    // For graphql: query variables
	Headers     map[string]string      `yaml:"headers,omitempty"`      // For rest: HTTP headers (env vars expanded)
	QueryParams map[string]string      `yaml:"query_params,omitempty"` // For rest: URL query parameters
	ResultPath  string                 `yaml:"result_path,omitempty"`  // For rest: dot-path to extract array (e.g., "data.items")
	Readonly    *bool                  `yaml:"readonly,omitempty"`     // For markdown/sqlite: read-only mode (default: true)
	Options     map[string]string      `yaml:"options,omitempty"`
	Manual      bool                   `yaml:"manual,omitempty"`    // For exec: require Run button click
	Format      string                 `yaml:"format,omitempty"`    // For exec: output format (json, lines, csv)
	Delimiter   string                 `yaml:"delimiter,omitempty"` // For exec CSV: field delimiter (default ",")
	Env         map[string]string      `yaml:"env,omitempty"`       // For exec: environment variables (env vars expanded)
	Timeout     string                 `yaml:"timeout,omitempty"`   // For exec/rest: timeout (e.g., "30s", "1m")
	AutoBind    *bool                  `yaml:"auto_bind,omitempty"` // Set to false to exclude from auto-table matching

	// For computed sources
	GroupBy   string            `yaml:"group_by,omitempty"`  // Field to group by
	Aggregate map[string]string `yaml:"aggregate,omitempty"` // Field → aggregation expression
	Filter    string            `yaml:"filter,omitempty"`    // Optional filter expression
}

type StatusType string

type StylingConfig struct {
	Theme        string `yaml:"theme"`
	PrimaryColor string `yaml:"primary_color"`
	Font         string `yaml:"font"`
}

type Tab struct {
	Name   string // Display name of the tab
	Filter string // Filter expression (empty for "All" tab)
}

type WasmBlock struct {
	ID            string
	Language      string // Currently only "go"
	DefaultCode   string
	ShowRunButton bool
	Metadata      map[string]string
}