state

type ClientAdapter interface {
	Realm(ctx context.Context, path, args string) ([]byte, error)
	ListPaths(ctx context.Context, prefix string, limit int) ([]string, error)
	Doc(ctx context.Context, path string, height int64) (*doc.JSONDocumentation, error)
	StatePkg(ctx context.Context, path string, height int64) ([]byte, error)
	StateObject(ctx context.Context, oid string, height int64) ([]byte, error)
	StateType(ctx context.Context, typeId string, height int64) ([]byte, error)
}

type DecodedObject struct {
	Nodes []StateNode
	Info  StateObjectInfoView
}

type Deps struct {
	Client      ClientAdapter
	Highlighter components.SnippetHighlighter
	// FileFetcher reads one source file by (pkgPath, fileName). Optional:
	// when nil, frag=source returns a fragment-error pointing at the
	// permanent ?source link. Wrapped per-request because the local
	// ClientAdapter cannot carry FileMeta without an import cycle.
	FileFetcher components.FileFetcher
	Logger      *slog.Logger
	// RateLimit configures the per-IP token bucket. Zero value disables it;
	// the limiter check in Handle becomes a no-op.
	RateLimit RateLimitConfig
}

type FragErrorData struct {
	Message   string
	RetryHint string
}

type FragNodeData struct {
	Node     StateNode
	PkgPath  string
	ViewMode string
	Depth    int
	// OID is the request's `?oid=…` — preserved separately because the
	// fragment's promoted root (func/closure inline) has no ObjectID of
	// its own. Drives the closure-tag OOB-swap target id.
	OID string
}

type FragSourceData struct {
	SourceHTML template.HTML
	PkgPath    string
	File       string
	Line       int
}

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

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

type KindCounts struct {
	All   int
	State int // struct, map, slice, array, pointer, ref
	Code  int // func, closure
	Types int // type, interface
}

type NamedDoc struct {
	Name string
	Doc  string
}

type Pagination struct {
	Total       int
	StartNumber int // 1-based inclusive; may collapse to 0 on empty page
	EndNumber   int
	HasPrev     bool
	HasNext     bool
	FirstHref   template.URL
	PrevHref    template.URL
	NextHref    template.URL
	LastHref    template.URL
}

type RateLimitConfig struct {
	PerMinute int // <=0 disables the limiter
	Burst     int // default = PerMinute
	MaxIPs    int // default 10_000
	// TrustedProxies is the set of trusted reverse-proxy networks. X-Real-IP
	// is honored ONLY when the connecting RemoteAddr falls inside one of
	// these CIDRs; empty = trust nothing (the safe default).
	TrustedProxies []*net.IPNet
	NowFunc        func() time.Time // injectable clock; default time.Now
}

type RenderConfig struct {
	// MaxChildrenPerNode caps visible children; surplus collapses to one
	// KindTruncated sentinel.
	MaxChildrenPerNode int
	// MaxDecodeDepth bounds recursion depth for this single decode.
	MaxDecodeDepth int
}

type SourceLocation struct {
	File      string
	StartLine int
	EndLine   int
}

type StateCrumb struct {
	Label string
	Href  template.URL
}

type StateData struct {
	PkgPath    string
	Nodes      []StateNode
	CountLabel string
	Crumbs     []StateCrumb
	Sidebar    *StateSidebar

	// ListHref is the current URL without `#fragment` — clicked to exit
	// the CSS focus mode by clearing the hash without a reload.
	ListHref template.URL

	// ViewMode is "tree" or "" (pretty default), derived from ?view= query param.
	ViewMode string

	// KindCounts feeds the kind-filter tab counters.
	KindCounts KindCounts

	// DocIndexJSON is the pre-marshaled qdoc projection over top-level
	// decls, embedded inline so the client-side controller can project
	// doc-comments onto htmx-loaded fragments without an extra RPC.
	DocIndexJSON template.JS

	// Pagination is the prev/next view-model for the top-level decls
	// footer. nil when total ≤ limit at offset 0 (no footer needed).
	Pagination *Pagination

	// SidebarTruncated is true when the full TOC exceeds maxSidebarTOC and
	// only the first cap entries are surfaced. The template renders a
	// "+N more — paginate to see them" hint when set.
	SidebarTruncated bool

	// SidebarTotal carries the realm's full top-level decl count so the
	// truncation hint can show the dropped-entry tail count (Total - cap).
	SidebarTotal int

	// SearchQuery is the validated `?search=` value. Empty when no filter
	// is active. Drives the banner + form input value in the template.
	SearchQuery string
}

type StateMetaEntry struct {
	Label string
	Value string
	// Href turns the value into a link when non-empty.
	Href template.URL
	// Mono renders blockchain IDs (OIDs, hashes) in truncated monospace.
	Mono bool
	// Section opens a new visual group; subsequent entries inherit it
	// until the next non-empty Section.
	Section string
	// Inline puts label + value on one line (compact).
	Inline bool
	// Block puts the value on its own row beneath the label (full-width).
	Block bool
}

type StateNode struct {
	Name       string
	Type       string
	Kind       string
	Value      string
	Expandable bool
	Children   []StateNode
	ObjectID   string
	TypeID     string
	Length     *int
	// Preview is a one-line summary of Children, rendered in
	// collapsed/ref rows. Re-computed after lazy ref fetches.
	Preview string
	Source  *SourceLocation
	// SourceHTML carries chroma-highlighted code; template.HTML so
	// html/template trusts it as already-safe markup.
	SourceHTML template.HTML
	// Href / OwnerHref are typed template.URL so html/template trusts them.
	Href      template.URL
	OwnerHref template.URL
	// Anchor is the row id stamped by Build{Package,Object}Sidebar for #
	// fragment linking from the TOC.
	Anchor string
	// ObjectInfo metadata captured by the walker from qobject_json/qpkg_json.
	Hash           string
	OwnerID        string
	ModTime        string
	RefCount       string
	LastObjectSize string
	// Doc is the plain-text source comment attached post-walk from the
	// package's JSON doc index, matched by Name. Rendered text-escaped
	// by the template — no Markdown processing.
	Doc string
}

type StateObjectInfoView struct {
	Hash, OwnerID, ModTime, RefCount, LastObjectSize string
	IsEscaped                                        bool
}

type StateSidebar struct {
	Heading string
	TOC     []StateTOCEntry
	Meta    []StateMetaEntry
}

type StateTOCEntry struct {
	Label      string
	Anchor     string
	Kind       string
	Type       string
	PrettyHref template.URL
	TreeHref   template.URL
	// OnPage marks entries that resolve to an in-page row id; off-page
	// entries set data-off-page="true" on the rendered <li>.
	OnPage bool
}