plugin

type ActionDesc struct {
	Method string  `json:"method"`
	Label  string  `json:"label"`
	Icon   string  `json:"icon,omitempty"`
	Danger bool    `json:"danger,omitempty"`
	Fields []Field `json:"fields,omitempty"`
	// Steps turns the action's form into a WIZARD: hope renders each step's fields in
	// order with Back/Next/Finish and a stepper. Values accumulate across steps, so a
	// later step's cascading options / conditional fields read earlier answers. Set via
	// ActionSteps; leave Fields empty when using Steps. The action receives the merged
	// values from every step, exactly like a flat form.
	Steps []WizardStep `json:"steps,omitempty"`
	Tip   *Tooltip     `json:"tip,omitempty"` // hover tooltip on the action button (set with ActionTip)
	// Prefill seeds the form's initial values by field Key, merged OVER the invoking
	// context (the clicked row's columns + the page params) — so commanding from a row
	// pre-selects its target and an explicit Prefill can override or add to that. The
	// operator can still edit; the submitted value wins. Set with ActionPrefill.
	Prefill map[string]string `json:"prefill,omitempty"`
	// ValidateMethod names a Validate provider (registered with Plugin.Validate). hope
	// calls it with the current values as they change; it returns per-field errors that
	// render inline and disable Run until the form is valid. Set with ActionValidate.
	ValidateMethod string `json:"validateMethod,omitempty"`
	// ConfirmMethod names a Confirm provider (registered with Plugin.Confirm). After the
	// form (and any Danger gate), hope calls it with the entered values to compute a
	// go/no-go impact confirmation; the operator must approve before the action runs. Set
	// with ActionConfirm.
	ConfirmMethod string `json:"confirmMethod,omitempty"`
}

type ActionFunc func(ctx context.Context, in map[string]any) (any, error)

type ActionOpt func(*ActionDesc)

type Capabilities struct {
	ViewKinds []string `json:"view_kinds"`
	Features  []string `json:"features"`
}

type Card struct {
	Title    string      `json:"title"`
	Subtitle string      `json:"subtitle,omitempty"`
	Icon     string      `json:"icon,omitempty"`
	Tone     string      `json:"tone,omitempty"` // ok|warn|bad|info accent
	To       string      `json:"to,omitempty"`
	Image    string      `json:"image,omitempty"` // absolute http(s) URL -> a hero image at the card top
	Fields   []CardField `json:"fields,omitempty"`
}

type CardField struct {
	Label string `json:"label"`
	Value any    `json:"value"`
}

type CardsData struct {
	Items []Card `json:"items"`
}

type Cell = map[string]any

type ChartData struct {
	Type   string        `json:"type,omitempty"`
	Labels []string      `json:"labels"`
	Series []ChartSeries `json:"series"`
}

type ChartSeries struct {
	Name   string    `json:"name"`
	Values []float64 `json:"values"`
}

type Comp struct {
	Kind     CompKind   `json:"kind"`
	Children []*Comp    `json:"children,omitempty"` // containers
	Text     string     `json:"text,omitempty"`     // text/heading content
	Label    string     `json:"label,omitempty"`    // keyval label
	Cell     Cell       `json:"cell,omitempty"`     // cell primitive: a rich Cell
	Value    any        `json:"value,omitempty"`    // keyval value (a scalar or a rich Cell)
	Level    int        `json:"level,omitempty"`    // heading level 1..4
	Tone     string     `json:"tone,omitempty"`     // ok|warn|bad|info accent (text/heading/keyval/box)
	Icon     string     `json:"icon,omitempty"`     // icon primitive
	Values   []float64  `json:"values,omitempty"`   // sparkline points
	Gap      int        `json:"gap,omitempty"`      // container child gap, px
	Size     int        `json:"size,omitempty"`     // row/grid child weight | spacer height px
	Table    *TableData `json:"table,omitempty"`    // embedded table (CompTable)
	Tree     []TreeNode `json:"tree,omitempty"`     // embedded node tree (CTree) — folders + navigable leaves
	// Tip is an optional hover tooltip (an info icon) on a labeled node — a Heading, a
	// KeyVal (by its key), or a Card title. Set with .Help(text). Lets a plugin attach
	// explanatory help ANYWHERE it renders a custom surface, the same way table headers use
	// ColumnTips and fields use Help.
	Tip *Tooltip `json:"tip,omitempty"`
	// State is a timeline step's progress: "done" | "current" | "pending" (default pending) —
	// drives the dot fill and the row's emphasis. Set with .Done()/.Current()/.Pending().
	State string `json:"state,omitempty"`
}

type CompKind string

type ConfirmFunc func(ctx context.Context) (ConfirmResult, error)

type ConfirmResult struct {
	Title        string `json:"title,omitempty"`
	Message      string `json:"message"`
	Danger       bool   `json:"danger,omitempty"`
	ConfirmLabel string `json:"confirmLabel,omitempty"`
}

type Contribution struct {
	Surface Surface    `json:"surface"`
	Title   string     `json:"title,omitempty"` // tab/page title
	Icon    string     `json:"icon,omitempty"`
	Match   *Match     `json:"match,omitempty"`
	Pages   []PageItem `json:"pages,omitempty"`
	Node    *Node      `json:"node"`
	// Actions are method names of registered actions shown as a toolbar at the top of
	// this surface (page/panel/dashboard header) — page-level actions distinct from
	// leaf actions inside the layout. hope collects fields, confirms danger, audits.
	Actions []string `json:"actions,omitempty"`
	// ID is a stable address for a page contribution, so links can target it by name
	// (a plugin does NOT know its hope key or a page's positional path). A DetailPage
	// sets ID + ParamKey and is Hidden from the rail; a Link/DetailLink navigates to
	// it plugin-relative, and hope passes the URL arg as param[ParamKey].
	ID       string `json:"id,omitempty"`
	Hidden   bool   `json:"hidden,omitempty"`    // not listed in the rail (a link/detail target)
	ParamKey string `json:"param_key,omitempty"` // detail pages: the URL arg becomes param[ParamKey]
	// Subtitle sets the page header's sub/meta line (page surfaces) — e.g. a record
	// count or a connection string. {param} placeholders are filled from the page
	// param. Empty => hope shows the plugin name.
	Subtitle string `json:"subtitle,omitempty"`
	// Breadcrumbs render above the page heading (page surfaces). Each Crumb's Label
	// and To may contain {param} placeholders hope fills from the page param — e.g.
	// on a user detail page, [{Users, users}, {"user {id}"}].
	Breadcrumbs []Crumb `json:"breadcrumbs,omitempty"`
}

type Crumb struct {
	Label string `json:"label"`
	To    string `json:"to,omitempty"`
}

type EmitFunc func(v any)

type EmptyOpt func(*EmptyState)

type EmptyState struct {
	Icon  string `json:"icon,omitempty"`  // leading icon (a built-in name or an Icons key)
	Title string `json:"title,omitempty"` // the headline, e.g. "No slow queries 🎉"
	Text  string `json:"text,omitempty"`  // a dim secondary line
	Comp  *Comp  `json:"comp,omitempty"`  // optional custom empty state (overrides Icon/Title/Text)
}

type Event struct {
	Seq     uint64          `json:"seq,omitempty"`
	Kind    string          `json:"kind"`
	Host    string          `json:"host,omitempty"`
	Project string          `json:"project,omitempty"`
	IDs     []string        `json:"ids,omitempty"`
	Source  string          `json:"source,omitempty"`
	Ts      int64           `json:"ts,omitempty"`
	Data    json.RawMessage `json:"data,omitempty"`
}

type EventFunc func(ctx context.Context, e Event) error

type Facet struct {
	Key     string   `json:"key"`
	Label   string   `json:"label"`
	Options []Option `json:"options"`
}

type Field struct {
	Key         string    `json:"key"`
	Label       string    `json:"label"`
	Type        FieldType `json:"type,omitempty"` // one of the Field* consts (default FieldText)
	Placeholder string    `json:"placeholder,omitempty"`
	Hint        string    `json:"hint,omitempty"` // a dim line UNDER the field (always visible)
	// Help is a longer explanation shown in a tooltip off a small info icon next to the
	// label — for detail that would clutter the form as an always-visible Hint. Both may
	// be set: Hint for the one-liner, Help for the "what is this / why" on hover.
	Help     string   `json:"help,omitempty"`
	Value    string   `json:"value,omitempty"`
	Optional bool     `json:"optional,omitempty"`
	Options  []Option `json:"options,omitempty"`
	// Number-field bounds/step/unit (Type:"number"). Unit renders as a suffix on the input.
	Min  float64 `json:"min,omitempty"`
	Max  float64 `json:"max,omitempty"`
	Step float64 `json:"step,omitempty"`
	Unit string  `json:"unit,omitempty"`
	// AllowCustom, on a Type:"combobox" field, lets the operator commit a typed value that
	// isn't in Options — a freeform entry with suggestions. Without it a combobox is a
	// type-ahead select restricted to the list. Ignored by other field types.
	AllowCustom bool `json:"allowCustom,omitempty"`
	// OptionsMethod names an Options provider (registered with Plugin.Options); when
	// set, hope fetches this select's choices from that method live as it renders the
	// form, instead of using the static Options above. The JSON key is camelCase to
	// match hope's PromptField, which the fields map onto directly.
	OptionsMethod string `json:"optionsMethod,omitempty"`
	// RefreshEvery, with OptionsMethod, re-fetches this select's options every N seconds
	// while the form is open — so a live label ("in contact / queues next pass", a changing
	// count) stays current without closing the modal. 0 (default) fetches once. camelCase to
	// match hope's PromptField.
	RefreshEvery int `json:"refreshEvery,omitempty"`
	// ResolveMethod names a Resolve provider (registered with Plugin.Resolve). When the
	// form's values change, hope calls it with the current values and renders the
	// returned component node inline below the fields — a selection can drive a live
	// preview, confirmation, or result. camelCase for the same PromptField reason.
	ResolveMethod string `json:"resolveMethod,omitempty"`
	// Fields is the per-item sub-schema of a Type:"group" field — a repeatable
	// array-of-objects the operator adds/removes rows of (a forms-builder). The action
	// receives the group's value as a []map[string]any, one map per row. AddLabel names
	// the "+ add" button.
	Fields   []Field `json:"fields,omitempty"`
	AddLabel string  `json:"addLabel,omitempty"`
	// DependsOn conditionally shows this field: it renders ONLY when the field named by
	// DependsOn currently equals DependsValue — or, when DependsValue is empty, when that
	// field is non-empty/truthy. Combine with OptionsMethod (which reads Params for the
	// current values) for cascading selects: choose A, and B's options refetch narrowed by
	// A — and B can stay hidden until A is set. camelCase to match hope's PromptField.
	DependsOn    string `json:"dependsOn,omitempty"`
	DependsValue string `json:"dependsValue,omitempty"`
	// FieldsMethod names a Fields provider (registered with Plugin.Fields). On this field's
	// change hope calls it with the current values (via Params) and renders the returned
	// []Field inline as a sub-form below this field — so a selection produces real, typed
	// inputs rather than a free-form box. The sub-fields may carry their own OptionsMethod /
	// DependsOn. camelCase to match hope's PromptField.
	FieldsMethod string `json:"fieldsMethod,omitempty"`
}

type FieldError struct {
	Key   string `json:"key"`
	Error string `json:"error"`
}

type FieldType string

type FieldsFunc func(ctx context.Context) ([]Field, error)

type GraphData struct {
	Nodes    []*GraphNode `json:"nodes"`
	Edges    []GraphEdge  `json:"edges,omitempty"`
	Directed bool         `json:"directed,omitempty"`
	// Active is the id of the DAG this data is for — set it so hope shows/highlights the
	// active DAG (in the sidebar, toolbar) and threads it to the chrome regions and run.
	Active string `json:"active,omitempty"`
}

type GraphEdge struct {
	From  string `json:"from"`
	To    string `json:"to"`
	Tone  string `json:"tone,omitempty"`
	Label string `json:"label,omitempty"`
}

type GraphMenuItem struct {
	Label   string `json:"label,omitempty"`
	Icon    string `json:"icon,omitempty"`
	Method  string `json:"method,omitempty"`
	Danger  bool   `json:"danger,omitempty"`
	Divider bool   `json:"divider,omitempty"` // a separator (Label ignored)
}

type GraphNode struct {
	ID    string  `json:"id"`
	Type  string  `json:"type,omitempty"`
	X     float64 `json:"x"`
	Y     float64 `json:"y"`
	W     int     `json:"w,omitempty"` // node width px (0 => hope default ~190)
	Title string  `json:"title,omitempty"`
	Icon  string  `json:"icon,omitempty"` // built-in name OR a plugin Icons key
	Tone  string  `json:"tone,omitempty"` // node accent
	// Meta is a clean, ordered key/value strip hope renders on the node face (its config /
	// params) — set it from the node's settings so populated params show without hand-building
	// a Body. Build with GNode(...).Meta(label, value). Body (below) is still available for
	// fully custom node content.
	Meta  []NodeMeta     `json:"meta,omitempty"`
	Body  *Comp          `json:"body,omitempty"`
	In    []Port         `json:"in,omitempty"`
	Out   []Port         `json:"out,omitempty"`
	State string         `json:"state,omitempty"` // run overlay: idle|running|done|error (drives the node glow)
	Data  map[string]any `json:"data,omitempty"`  // opaque; echoed back to mutation methods
	// Fields is an optional per-node config form. When set (and the view has GraphConfig),
	// clicking the node opens these Fields — the SAME dynamic form as an action, so a node
	// gets real inputs: a select populated from an OptionsMethod, number, multiselect, etc.
	// The form prefills from Data (matching keys); submitting calls the GraphConfig method
	// with {id, ...values}. Build with GNode(...).Form(...).
	Fields []Field `json:"fields,omitempty"`
	// Actions render as a button bar at the bottom of the node card (Info / Logs / …). Each
	// runs its Method with {id, ...Data}; the result can steer the UI (a flyout/navigate
	// directive), so an "Info" action can open a modal explaining what the node does. Reuses
	// RowAction (Icon/Danger/Fields/Tip). Build with GNode(...).Act(...).
	Actions []RowAction `json:"actions,omitempty"`
}

type GraphOpt = TableOpt

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

type ImageOpt func(map[string]any)

type InitContext struct {
	Settings map[string]string
	Protocol int
	Caps     Capabilities
}

type Item struct {
	Type string         `json:"type,omitempty"`
	Data map[string]any `json:"data,omitempty"`
	Comp *Comp          `json:"comp,omitempty"`
}

type KVData = map[string]any

type Layout struct {
	ProtocolVersion int            `json:"protocolVersion"`
	Contributions   []Contribution `json:"contributions"`
}

type Match struct {
	Always   bool              `json:"always,omitempty"`   // every container
	Images   []string          `json:"images,omitempty"`   // image-ref globs, e.g. "postgres*"
	Labels   map[string]string `json:"labels,omitempty"`   // label == value
	Services []string          `json:"services,omitempty"` // compose service names
}

type Node struct {
	Kind  NodeKind `json:"kind"`
	Title string   `json:"title,omitempty"`
	Ref   string   `json:"ref,omitempty"`  // leaf: method name of a view/action/stream
	Size  int      `json:"size,omitempty"` // optional row/grid weight
	Fill  bool     `json:"fill,omitempty"` // grow to fill the remaining height (e.g. a table)
	// Collapsible makes a titled section fold on a title click; Collapsed starts it
	// closed. For dense pages where not everything needs to be open at once.
	Collapsible bool    `json:"collapsible,omitempty"`
	Collapsed   bool    `json:"collapsed,omitempty"`
	Children    []*Node `json:"children,omitempty"`
	// Comp carries an inline Component tree when Kind is NodeComponent (see Component).
	Comp *Comp `json:"comp,omitempty"`
}

type NodeKind string

type NodeMeta struct {
	Label string `json:"label"`
	Value string `json:"value"`
	Tone  string `json:"tone,omitempty"`
}

type NodeType struct {
	Type     string `json:"type"`
	Label    string `json:"label,omitempty"`
	Icon     string `json:"icon,omitempty"`
	Tone     string `json:"tone,omitempty"`
	Category string `json:"category,omitempty"` // groups the palette
	Desc     string `json:"desc,omitempty"`     // tooltip
}

type Option struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type OptionsFunc func(ctx context.Context) ([]Option, error)

type Page struct {
	Items      []Item `json:"items"`
	Total      int    `json:"total,omitempty"`
	NextCursor string `json:"nextCursor,omitempty"`
}

type PageItem struct {
	Title    string         `json:"title"`
	Icon     string         `json:"icon,omitempty"`
	Param    map[string]any `json:"param,omitempty"`
	Children []PageItem     `json:"children,omitempty"`
}

type Permission struct {
	Scope  string `json:"scope"`
	Reason string `json:"reason,omitempty"`
}

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

type Port struct {
	ID    string `json:"id"`
	Label string `json:"label,omitempty"`
	Kind  string `json:"kind,omitempty"`
	Tone  string `json:"tone,omitempty"`
}

type ResolveFunc func(ctx context.Context) (any, error)

type RowAction struct {
	Method string   `json:"method"`
	Label  string   `json:"label"`
	Icon   string   `json:"icon,omitempty"`
	Danger bool     `json:"danger,omitempty"` // hope confirms before running and audit-logs it
	Fields []Field  `json:"fields,omitempty"` // optional input collected before the call
	Tip    *Tooltip `json:"tip,omitempty"`    // hover tooltip on the row action button (build with Tip)
	// ShowWhenKey/ShowWhenValue gate the button PER ROW against that row's cells: the
	// button shows only when the row's ShowWhenKey cell equals ShowWhenValue (or, when
	// ShowWhenValue is empty, when that cell is non-empty/truthy). Mirrors Field.DependsOn/
	// DependsValue. Applies to the inline row button AND the RowFlyout footer. Empty
	// ShowWhenKey = always shown (unchanged). A Badge/Code/Link cell compares by its text.
	ShowWhenKey   string `json:"showWhenKey,omitempty"`
	ShowWhenValue string `json:"showWhenValue,omitempty"`
	// DisableInsteadOfHide renders the button disabled (greyed, Tip as the reason) instead
	// of hidden when the predicate fails — so the operator sees it exists but can't use it.
	DisableInsteadOfHide bool `json:"disableInsteadOfHide,omitempty"`
}

type Schema struct {
	ProtocolVersion int               `json:"protocolVersion"`
	Name            string            `json:"name"`
	Version         string            `json:"version"`
	Description     string            `json:"description,omitempty"`
	Icon            string            `json:"icon,omitempty"`  // default icon: a hope built-in OR an Icons key
	Icons           map[string]string `json:"icons,omitempty"` // plugin-scoped {name: inner-svg-markup}
	Actions         []ActionDesc      `json:"actions"`
	Views           []ViewDesc        `json:"views"`
	Streams         []StreamDesc      `json:"streams"`
	Settings        []Setting         `json:"settings,omitempty"`    // operator-managed config (see Setting)
	Permissions     []Permission      `json:"permissions,omitempty"` // reverse-capability requests (see Permission)
}

type SearchData struct {
	Items []SearchItem `json:"items"`
}

type SearchItem struct {
	Label string `json:"label"`
	Sub   string `json:"sub,omitempty"`
	Image string `json:"image,omitempty"`
	To    string `json:"to"`
}

type Setting struct {
	Key     string      `json:"key"`
	Label   string      `json:"label"`
	Kind    SettingKind `json:"kind,omitempty"` // default text
	Default string      `json:"default,omitempty"`
	Hint    string      `json:"hint,omitempty"`
	Options []Option    `json:"options,omitempty"` // for kind=select
}

type SettingKind string

type SortSpec struct {
	Column string `json:"column"`
	Dir    string `json:"dir"`
}

type StatBlock struct {
	Label string   `json:"label"`
	Value any      `json:"value"`
	Unit  string   `json:"unit,omitempty"`
	Sub   string   `json:"sub,omitempty"`
	Tone  string   `json:"tone,omitempty"` // ok|warn|bad|info
	Icon  string   `json:"icon,omitempty"`
	Tip   *Tooltip `json:"tip,omitempty"` // hover tooltip explaining the metric (build with Tip)
}

type StatData struct {
	Stats []StatBlock `json:"stats"`
}

type StatusReport struct {
	Status string `json:"status"`           // short human status ("primary", "3/3 replicas", "lag 4s")
	Level  string `json:"level"`            // ok | info | warn | error
	Detail string `json:"detail,omitempty"` // optional longer explanation
}

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

type StreamDesc struct {
	Method string     `json:"method"`
	Label  string     `json:"label"`
	Kind   StreamKind `json:"kind"`
	Icon   string     `json:"icon,omitempty"`
}

type StreamFunc func(ctx context.Context, emit EmitFunc) error

type StreamKind string

type Surface string

type TableData struct {
	Columns []string `json:"columns"`
	Rows    [][]any  `json:"rows"`
	Total   int      `json:"total"`
	Hidden  []string `json:"hidden,omitempty"`
	// ColumnTips maps a column name to a hover tooltip on its header — for clarifying
	// a terse or computed column (e.g. "health": Tip("seq-scan / bloat state")).
	ColumnTips map[string]*Tooltip `json:"column_tips,omitempty"`
	// RowMethod makes rows clickable, opening the row-detail modal via that method —
	// the data-side equivalent of the RowDetail table option (for views without opts,
	// like a QueryView).
	RowMethod string `json:"row_method,omitempty"`
	// RowFlyout makes rows clickable into a right-side DRAWER instead of a modal. The
	// method receives the clicked {row} and returns a component tree (plugin.Box(...)) hope
	// renders in the flyout. Data-side equivalent of the RowFlyout table option. When both
	// RowFlyout and RowMethod are set, the flyout wins.
	RowFlyout string `json:"row_flyout,omitempty"`
	// RowFlyoutWidth sizes the drawer the flyout opens in: a preset ("small" | "large" |
	// "xlarge") or an explicit px value ("680"). Empty = the default (~460px).
	RowFlyoutWidth string `json:"row_flyout_width,omitempty"`
	// RowFlyoutRefresh, when > 0, makes an OPEN flyout re-invoke its method every N seconds
	// with the same row and swap the body in place (scroll preserved) — so a live drawer
	// (e.g. a lifecycle Timeline) follows along without reopening. 0 = one-shot (default).
	RowFlyoutRefresh int `json:"row_flyout_refresh,omitempty"`
	// Flush renders the table full-height with no toolbar (filter/pager) and no inner scroll
	// box — it flows and the containing panel/flyout scrolls instead. Meant for an embedded
	// CTable showing a bounded list (e.g. the badges on a canvas), not a big paged view.
	Flush bool `json:"flush,omitempty"`
	// Scroll lets a WIDE table (many columns) scroll HORIZONTALLY — each column keeps its
	// natural width and a scrollbar appears — instead of cramming every column into the
	// container so nothing feels squeezed. Set with HScroll.
	Scroll bool `json:"scroll,omitempty"`
}

type TableOpt func(*ViewDesc)

type TableQuery struct {
	Page     int               `json:"page"`
	PageSize int               `json:"page_size"`
	Sort     TableSort         `json:"sort"`
	Filter   string            `json:"filter"`
	Filters  map[string]string `json:"filters"`
}

type TableSort struct {
	Column string `json:"column"`
	Dir    int    `json:"dir"`
}

type TextData struct {
	Text string `json:"text"`
}

type TipPos string

type Tooltip struct {
	Text string `json:"text"`
	Pos  TipPos `json:"pos,omitempty"`
}

type TreeData struct {
	Nodes []TreeNode `json:"nodes"`
}

type TreeNode struct {
	Label     string     `json:"label"`
	Icon      string     `json:"icon,omitempty"` // built-in icon name or an Icons key
	Tone      string     `json:"tone,omitempty"` // ok|warn|bad|info dot
	To        string     `json:"to,omitempty"`   // plugin-relative nav target (like a Link cell)
	Collapsed bool       `json:"collapsed,omitempty"`
	Tip       *Tooltip   `json:"tip,omitempty"`
	Children  []TreeNode `json:"children,omitempty"`
	// Actions are per-node buttons (rename/delete/…), shown on hover — reuses RowAction, so
	// Icon/Danger/Fields/Tip all work. Clicking one runs its Method with Args as the {row}.
	Actions []RowAction    `json:"actions,omitempty"`
	Args    map[string]any `json:"args,omitempty"` // the {row} context passed to this node's Actions
}

type ValidateFunc func(ctx context.Context) ([]FieldError, error)

type ViewDesc struct {
	Method string   `json:"method"`
	Label  string   `json:"label"`
	Kind   ViewKind `json:"kind"`
	Icon   string   `json:"icon,omitempty"`
	// Empty customizes the "no data" state (see EmptyState); unset => hope's generic text.
	Empty   *EmptyState `json:"empty,omitempty"`
	Lang    string      `json:"lang,omitempty"`    // query views: syntax-highlight language (sql, json, …)
	Default string      `json:"default,omitempty"` // query views: initial text; {param} placeholders are filled from the page param
	// RowMethod (table/query views): a method hope calls to open a row-detail modal,
	// with params {row: {column: value}}. The result (kv or table) is shown in a
	// modal — a fully author-controlled row-detail RPC.
	RowMethod string `json:"row_method,omitempty"`
	// RowFlyout (table/query views): like RowMethod but opens a right-side DRAWER instead
	// of a modal. The method receives {row} and returns a component tree hope renders in
	// the flyout. When both are set, the flyout wins.
	RowFlyout string `json:"row_flyout,omitempty"`
	// RowFlyoutWidth sizes the drawer: a preset ("small" | "large" | "xlarge") or an
	// explicit px value ("680"). Empty = the default (~460px).
	RowFlyoutWidth string `json:"row_flyout_width,omitempty"`
	// RowFlyoutRefresh re-invokes an OPEN flyout's method every N seconds (same row) and
	// swaps the body in place — a live drawer. 0 = one-shot (default). Set with RowFlyoutRefresh.
	RowFlyoutRefresh int `json:"row_flyout_refresh,omitempty"`
	// Scroll lets a WIDE table view (many columns) scroll HORIZONTALLY — columns keep their
	// natural width and a scrollbar appears — instead of cramming them into the container.
	// Set with HScroll.
	Scroll bool `json:"scroll,omitempty"`
	// --- Paged view (ViewKind Paged) ---
	// ItemTemplates maps an Item's Type -> a component template (B). Placeholders {field} in
	// the template's text/values are bound to the item's Data. Register with ItemTemplate.
	ItemTemplates map[string]*Comp `json:"item_templates,omitempty"`
	// Layout arranges a Paged view's items: "list" (default) | "grid" | "flow". Set with Layout.
	Layout string `json:"layout,omitempty"`
	// Infinite renders a Paged view with load-more-on-scroll instead of a pager. Set with Infinite.
	Infinite bool `json:"infinite,omitempty"`
	// RowDetailButton triggers RowMethod from a dedicated per-row button instead of a
	// whole-row click. Use when the row body is otherwise interactive (e.g. inline-
	// editable cells) so the two don't fight.
	RowDetailButton bool `json:"row_detail_button,omitempty"`
	// RowActions (table/query views): per-row action buttons. hope renders each in a
	// trailing column (and in the row-detail modal); clicking one calls its Method
	// with {row: {column: value}} — an author-controlled mutation like "delete row".
	// A Danger action is confirmed first; on success hope refetches the table.
	RowActions []RowAction `json:"row_actions,omitempty"`
	// PageSize (table/query views) sets how many rows hope shows per page — the
	// author knows the shape of their data, so paging is plugin-level. 0 => hope's
	// default.
	PageSize int `json:"page_size,omitempty"`
	// EditMethod (table/query views): editing a cell calls this method with
	// {row: {column: value}, column, value}. Return ok (and optionally a message).
	// EditColumns limits which columns are editable (empty => all). An
	// author-controlled inline-edit RPC — hope refetches the table on success.
	EditMethod  string   `json:"edit_method,omitempty"`
	EditColumns []string `json:"edit_columns,omitempty"`
	// Server marks a table server-driven: hope does NOT ship every row and page in
	// the browser. Instead it sends the query state ({_q: {page, page_size, sort,
	// filter}}) on each call and expects one page back plus a total row count
	// ({columns, rows, total}). Required for tables too large to send whole — read
	// the query with plugin.ReadTableQuery.
	Server bool `json:"server,omitempty"`
	// Refresh adds a manual refresh button to the view header that re-fetches it —
	// e.g. a stat/counter you want to recompute on demand.
	Refresh bool `json:"refresh,omitempty"`
	// RefreshInterval auto-refetches the view every N seconds (0 = off) — a live-ish
	// view without a stream. hope stops the timer when the view leaves the DOM.
	RefreshInterval int `json:"refresh_interval,omitempty"`
	// Static marks a view's data as fixed for the life of the surface: hope fetches it
	// once and serves the cached result on tab re-entry / re-navigation instead of
	// re-calling the plugin — cutting round-trips and easing the per-plugin rate limit.
	// A manual Refresh() button still forces a re-fetch, so Static()+Refresh() = "load
	// once, refresh on demand". Don't combine with RefreshInterval.
	Static bool `json:"static,omitempty"`
	// Facets (server tables) are dropdown filters hope renders in the toolbar; the
	// selected values arrive in the query as filters[key] (see TableQuery.Filters),
	// which you apply in your store. Distinct from the free-text search box.
	Facets []Facet `json:"facets,omitempty"`
	// DefaultSort (server tables) is the sort hope applies on FIRST load, before the
	// user clicks any column header — e.g. newest-indexed first. hope seeds the query
	// state with it (so it arrives in TableQuery.Sort) and shows the arrow on that
	// column. The user can still re-sort. Column must be one your handler accepts.
	DefaultSort *SortSpec `json:"default_sort,omitempty"`
	// NoFilter hides the search box and NoSort makes column headers non-interactive —
	// for a plain paged list (a fixed order your handler controls, no user search/sort).
	NoFilter bool `json:"no_filter,omitempty"`
	NoSort   bool `json:"no_sort,omitempty"`
	// --- Graph view (ViewKind Graph) — all optional method refs; a bare GraphView is just
	// the canvas. Set with the Graph* opts. hope calls each mutation with {row:{...}} (like a
	// RowAction) and re-fetches the graph on success. ---
	GraphMove            string     `json:"graph_move,omitempty"`             // persist a dragged node's position {id,x,y}
	GraphConnect         string     `json:"graph_connect,omitempty"`          // add an edge {from:"n:p", to:"n:p"}
	GraphDisconnect      string     `json:"graph_disconnect,omitempty"`       // remove an edge {from,to}
	GraphDelete          string     `json:"graph_delete,omitempty"`           // delete a node {id}
	GraphAdd             string     `json:"graph_add,omitempty"`              // create a node {type,x,y} (palette drop / dbl-click)
	GraphNodeFlyout      string     `json:"graph_node_flyout,omitempty"`      // node click -> a Comp body in the drawer {id}
	GraphConfig          string     `json:"graph_config,omitempty"`           // persist a node's config form: {id, ...field values}
	GraphMenu            string     `json:"graph_menu,omitempty"`             // right-click -> []GraphMenuItem for {kind, id/from/to}
	GraphValidateConnect string     `json:"graph_validate_connect,omitempty"` // optional pre-connect gate {from,to} -> {ok,reason}
	GraphRun             string     `json:"graph_run,omitempty"`              // a StreamComponent-kind stream emitting GraphData frames (run highlight)
	GraphSidebar         string     `json:"graph_sidebar,omitempty"`          // left rail: a Comp (browse the plugin's DAGs) {}
	GraphSidebarActions  []string   `json:"graph_sidebar_actions,omitempty"`  // action-method refs rendered as buttons atop the sidebar (New, ...)
	GraphToolbar         string     `json:"graph_toolbar,omitempty"`          // top strip: a Comp (title/run/filters) {}
	GraphSelect          string     `json:"graph_select,omitempty"`           // sidebar row click -> set active graph {id}; canvas refetches with {graph:id}
	GraphPalette         string     `json:"graph_palette,omitempty"`          // the node-TYPE catalog: returns []NodeType
	GraphTypeInfo        string     `json:"graph_type_info,omitempty"`        // palette info button -> a Comp about a node TYPE {type} (view before adding)
	Palette              []NodeType `json:"palette,omitempty"`                // a STATIC node-type catalog (alternative to GraphPalette)
	GraphDirected        bool       `json:"graph_directed,omitempty"`         // draw arrowheads on edges
	GraphSnap            int        `json:"graph_snap,omitempty"`             // snap dragged nodes to an N-px grid (0 = free)
}

type ViewFunc func(ctx context.Context) (any, error)

type ViewKind string

type ViewOpt = TableOpt

type WizardStep struct {
	Title  string  `json:"title,omitempty"`
	Hint   string  `json:"hint,omitempty"`
	Fields []Field `json:"fields"`
}