server

type AppliedNavigateOptions struct {
	Replace bool
	Params  map[string]any
	Scroll  bool
}

type AuthCheckConfig struct {
	// Interval between active checks (0 disables periodic checks).
	Interval time.Duration

	// Timeout caps how long a Check may take.
	// Default: 5 seconds.
	Timeout time.Duration

	// FailureMode controls transient failure handling.
	// Default: FailOpenWithGrace.
	FailureMode AuthFailureMode

	// MaxStale caps how long a session may go without a successful active check
	// when FailureMode is fail-open.
	// Default: 15 minutes.
	MaxStale time.Duration

	// Check is called periodically and on-demand.
	// This runs off the session loop; do not mutate session state directly.
	// Panics are recovered and treated as check failures.
	Check func(ctx context.Context, p auth.Principal) error

	// OnExpired defines what happens when auth fails.
	OnExpired AuthExpiredConfig
}

type AuthExpiredAction int

type AuthExpiredConfig struct {
	Action  AuthExpiredAction
	Path    string
	Reason  AuthExpiredReason
	Handler func(s *Session)
}

type AuthExpiredReason int

type AuthFailureMode int

type AuthResumePolicy int

type BudgetExceededMode int

type ByteSize int64

type CSPOptions struct {
	ReportOnly         bool
	AllowInlineStyles  bool
	AllowInlineScripts bool
	AllowDataImages    bool
	AllowHTTPSImages   bool
	// IncludeWSS allows scheme-wide secure websocket egress in connect-src.
	// Prefer exact websocket origins via AdditionalConnectSrc when possible.
	IncludeWSS bool
	// IncludeWS allows scheme-wide insecure websocket egress in connect-src.
	// Prefer exact websocket origins via AdditionalConnectSrc when possible.
	IncludeWS bool

	AdditionalConnectSrc []string
	AdditionalScriptSrc  []string
	AdditionalStyleSrc   []string
	AdditionalImgSrc     []string
	AdditionalFontSrc    []string
	AdditionalDirectives []string
}

type CSRFError struct {
	Reason string
}

type Component interface {
	// Render returns the VNode tree for this component.
	Render() *vdom.VNode
}

type ComponentInstance struct {
	// InstanceID is the unique instance identifier.
	InstanceID string

	// Component is the component being rendered.
	Component Component

	// HID is the hydration ID of the root element.
	HID string

	// Owner manages signal ownership for this component.
	Owner *vango.Owner

	// Parent is the parent component instance (nil for root).
	Parent *ComponentInstance

	// Children are child component instances.
	Children []*ComponentInstance

	// Props are the current props passed to the component.
	Props map[string]any
	// contains filtered or unexported fields
}

type CookieOption func(*CookiePolicyOptions)

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

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

type Ctx interface {

	// Request returns the underlying HTTP request.
	Request() *http.Request

	// Path returns the URL path.
	Path() string

	// Method returns the HTTP method.
	Method() string

	// Query returns the URL query parameters as url.Values.
	Query() url.Values

	// QueryParam returns a single query parameter value by key.
	// Returns an empty string if the key is not present.
	QueryParam(key string) string

	// Param returns a route parameter by key.
	Param(key string) string

	// Header returns a request header value.
	Header(key string) string

	// Cookie returns a cookie by name.
	Cookie(name string) (*http.Cookie, error)

	// Status sets the HTTP response status code.
	Status(code int)

	// Redirect redirects to the given URL with the given status code.
	// Redirects are relative-only and reject absolute URLs.
	Redirect(url string, code int)

	// RedirectExternal redirects to an absolute URL with the given status code.
	// External redirects require an explicit allowlist.
	RedirectExternal(url string, code int)

	// SetHeader sets a response header.
	SetHeader(key, value string)

	// SetCookie sets a response cookie.
	SetCookie(cookie *http.Cookie)

	// SetCookieStrict sets a response cookie with enforced security defaults.
	// Returns ErrSecureCookiesRequired if secure cookies are enabled and the request is not secure.
	SetCookieStrict(cookie *http.Cookie, opts ...CookieOption) error

	// Session returns the WebSocket session (nil for SSR-only requests).
	Session() vango.Session

	// Surface returns normalized metadata for the current connected surface.
	Surface() surface.Info

	// Shell returns the shell bridge for the current surface.
	Shell() shell.Bridge

	// AuthSession returns the WebSocket session as an auth.Session interface.
	// This allows auth helpers to persist to the session without importing server.
	AuthSession() auth.Session

	// User returns the authenticated user (set by auth middleware).
	User() any

	// SetUser sets the authenticated user.
	SetUser(user any)

	// Principal returns the authenticated principal, if any.
	Principal() (auth.Principal, bool)

	// MustPrincipal returns the principal or panics if not set.
	MustPrincipal() auth.Principal

	// RevalidateAuth forces an immediate active check if configured.
	// Returns any error from the check, including ErrAuthCheckPanicked when
	// the configured check panics.
	// If authenticated session projection exists but principal is missing,
	// this fails closed with auth.ErrSessionExpired.
	RevalidateAuth() error

	// BroadcastAuthLogout notifies other tabs that auth was cleared and they should reload.
	BroadcastAuthLogout()

	// Logger returns the request-scoped logger.
	Logger() *slog.Logger

	// Done returns a channel that's closed when the request is canceled.
	// It does not represent the SSR page render budget.
	Done() <-chan struct{}

	// SetValue stores a request-scoped value.
	// These values are only available for the duration of the current event/request.
	SetValue(key, value any)

	// Value retrieves a request-scoped value.
	Value(key any) any

	// Emit dispatches a custom event to the client.
	// The event will be dispatched as a CustomEvent with the given name and detail.
	// Use this for notifications, toast messages, analytics, etc.
	Emit(name string, data any)

	// Focus moves browser focus to a mounted element with the given DOM id.
	// It is a live-session side effect and is ignored during SSR-only requests.
	Focus(id string)

	// Blur removes browser focus from a mounted element with the given DOM id.
	// It is a live-session side effect and is ignored during SSR-only requests.
	Blur(id string)

	// FocusHID moves browser focus to a mounted element by Vango HID.
	// Prefer Focus with a stable DOM id in application code; use FocusHID when
	// intentionally targeting the current event element via ctx.Event().HID.
	FocusHID(hid string)

	// BlurHID removes browser focus from a mounted element by Vango HID.
	// Prefer Blur with a stable DOM id in application code; use BlurHID when
	// intentionally targeting the current event element via ctx.Event().HID.
	BlurHID(hid string)

	// Dispatch queues a function to run on the session's event loop.
	// This is safe to call from any goroutine and is the correct way to
	// update signals from asynchronous operations (database calls, timers, etc.).
	//
	// The function will be executed synchronously on the event loop, ensuring
	// signal writes are properly serialized. After the function completes,
	// pending effects will run and dirty components will re-render.
	//
	// Example:
	//
	//     go func() {
	//         user, err := db.Users.FindByID(ctx.StdContext(), id)
	//         ctx.Dispatch(func() {
	//             if err != nil {
	//                 errorSignal.Set(err)
	//             } else {
	//                 userSignal.Set(user)
	//             }
	//         })
	//     }()
	//
	// IMPORTANT: This method MUST be safe to call from any goroutine.
	Dispatch(fn func())

	// Navigate performs a client-side navigation to the given path.
	// Unlike Redirect(), this updates the browser URL and re-renders the page
	// without a full HTTP redirect. The navigation is queued and processed
	// after the current handler completes.
	//
	// Options can be provided to customize behavior:
	//   - WithReplace() - replace current history entry instead of pushing
	//   - WithNavigateParams(map[string]any) - add query parameters to the URL
	//   - WithoutScroll() - disable scrolling to top after navigation
	//
	// Example:
	//
	//     func handleSave(ctx vango.Ctx) {
	//         project := saveProject()
	//         ctx.Navigate("/projects/" + project.ID)
	//     }
	//
	// For HTTP-only requests (SSR without WebSocket), this falls back to
	// an HTTP redirect.
	Navigate(path string, opts ...NavigateOption)

	// StdContext returns the standard library context with trace propagation.
	// Use this when calling external services or database drivers.
	//
	// Example:
	//     row := db.QueryRowContext(ctx.StdContext(), "SELECT * FROM users WHERE id = $1", userID)
	//     req, _ := http.NewRequestWithContext(ctx.StdContext(), "GET", url, nil)
	//
	// The context includes any trace spans injected by middleware (e.g., OpenTelemetry).
	// During SSR, it may also carry the configured page render deadline.
	StdContext() context.Context

	// WithStdContext updates the standard context used by StdContext().
	// This is used by middleware to inject trace spans for downstream calls.
	//
	// This is typically called by observability middleware:
	//     spanCtx, span := tracer.Start(ctx.StdContext(), "operation")
	//     defer span.End()
	//     ctx = ctx.WithStdContext(spanCtx)
	//     return next()
	WithStdContext(stdCtx context.Context) Ctx

	// Event returns the current WebSocket event being processed.
	// Returns nil for HTTP-only requests (SSR).
	//
	// Example:
	//     if event := ctx.Event(); event != nil {
	//         log.Printf("Processing %s event on %s", event.Type, event.HID)
	//     }
	Event() *Event

	// PatchCount returns the number of patches sent during this request.
	// This is updated after each render cycle.
	PatchCount() int

	// AddPatchCount increments the patch count for this request.
	// Called internally by the render system.
	AddPatchCount(count int)

	// StormBudget returns the storm budget checker for this session.
	// Used by primitives (Action, Resource, GoLatest) to check rate limits.
	// Returns nil if storm budgets are not configured.
	//
	// See SPEC_ADDENDUM.md §A.4 for storm budget configuration.
	StormBudget() vango.StormBudgetChecker

	// Mode returns the current render mode as int.
	// Returns 0 (ModeNormal) for regular requests, 1 (ModePrefetch) during prefetch.
	//
	// Primitives like Effect, Interval, and signal.Set() check this to
	// enforce read-only behavior during prefetch:
	//   - ModePrefetch (1): Signal writes are dropped, effects are no-ops
	//   - ModeNormal (0): All operations proceed normally
	//
	// This method implements vango.PrefetchModeChecker interface.
	//
	// Example (for primitive implementations):
	//     if ctx := UseCtx(); ctx != nil && ctx.Mode() == 1 {
	//         if DevMode { panic("signal write forbidden in prefetch") }
	//         return // drop in prod
	//     }
	Mode() int

	// Asset resolves a source asset path to its fingerprinted path.
	// Returns the original path if no manifest is configured or the asset is not found.
	//
	// This enables cache-busting via content-hashed filenames while keeping
	// templates simple:
	//
	// Example:
	//
	//     <script src={ctx.Asset("vango.js")}></script>
	//     // In dev: "/public/vango.js"
	//     // In prod: "/public/vango.a1b2c3d4.min.js"
	Asset(source string) string
}

type Event struct {
	// Seq is the sequence number of the event.
	Seq uint64

	// Type is the type of event (click, input, submit, etc.).
	Type protocol.EventType

	// HID is the hydration ID of the target element.
	HID string

	// Payload contains type-specific event data.
	Payload any

	// Session is the session that received the event.
	Session *Session

	// Time is when the event was received by the server.
	Time time.Time
	// contains filtered or unexported fields
}

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

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

type FuncComponent func() *vdom.VNode

type Handler func(event *Event)

type HandlerError struct {
	SessionID string
	HID       string
	EventType string
	Panic     any
	Stack     []byte
}

type HealthCheck func(r *http.Request) error

type HookEvent struct {
	Name string
	Data map[string]any
}

type HostedSurfaceAllowedSurface struct {
	Kind     surface.Kind
	Platform surface.Platform
}

type HostedSurfaceIdentity struct {
	Surface surface.Info
}

type HostedSurfaceVerifierConfig struct {
	// ProofSecret verifies the native host's X-Vango-Surface-Proof-* headers.
	// Use at least 32 random bytes and keep it separate from the server-only
	// HostedSurfaceTokenSecret.
	ProofSecret []byte

	// AllowedOrigins are the trusted hosted web origins that may receive native
	// hosted surface bootstrap. Entries must be origins, for example
	// "https://app.example.com".
	AllowedOrigins []string

	// AllowedSurfaces restricts which native hosted surfaces may assert trust.
	// Defaults to the first-party Vango native hosts: macOS desktop and iOS mobile.
	AllowedSurfaces []HostedSurfaceAllowedSurface

	// MaxClockSkew bounds signed proof freshness. Defaults to 5 minutes.
	MaxClockSkew time.Duration

	// Now is injectable for tests. Defaults to time.Now.
	Now func() time.Time
}

type HostedSurfaceVerifyFunc func(r *http.Request) (*HostedSurfaceIdentity, error)

type InstancePath struct {
	RouteID  string
	KeyPath  []string
	StableID string
}

type KeyboardEvent struct {
	Key      string
	CtrlKey  bool
	ShiftKey bool
	AltKey   bool
	MetaKey  bool
}

type LayoutHandler func(ctx Ctx, children vango.Slot) *vdom.VNode

type ManagerStats struct {
	Active       int
	TotalCreated uint64
	TotalClosed  uint64
	Peak         int
	TotalMemory  int64
}

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

type MemoryMonitorConfig struct {
	SoftLimit     int64         // Bytes at which to start evicting (default: 80% of system memory)
	HardLimit     int64         // Bytes at which to aggressively evict (default: 90% of system memory)
	CheckInterval time.Duration // How often to check memory (default: 10s)
	GCCooldown    time.Duration // Minimum time between forced GCs (default: 30s)
}

type MemoryPressureLevel int

type MemoryStats struct {
	HeapAlloc    int64         // Bytes allocated on heap
	HeapSys      int64         // Bytes obtained from OS for heap
	HeapIdle     int64         // Bytes in idle spans
	HeapInuse    int64         // Bytes in non-idle spans
	HeapReleased int64         // Bytes released to OS
	StackInuse   int64         // Bytes used by stack
	NumGC        uint32        // Number of completed GC cycles
	LastGC       time.Time     // Time of last GC
	GCPauseTotal time.Duration // Total GC pause time
}

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

type Middleware func(http.Handler) http.Handler

type MouseEvent struct {
	ClientX  int
	ClientY  int
	Button   int
	CtrlKey  bool
	ShiftKey bool
	AltKey   bool
	MetaKey  bool
}

type NavigateEvent struct {
	Path    string
	Replace bool
}

type NavigateOption func(*navigateOptions)

type NavigateResult struct {
	// Path is the canonicalized path that was navigated to
	Path string

	// Matched indicates if a route was matched
	Matched bool

	// Patches contains the DOM patches from the navigation
	Patches []vdom.Patch

	// NavPatch is the NAV_PUSH or NAV_REPLACE patch
	NavPatch protocol.Patch

	// Error contains any error that occurred
	Error error
}

type OriginPolicyMode int

type PageHandler func(ctx Ctx, params any) Component

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

type PatchHistoryEntry struct {
	Seq    uint64    // Patch sequence number
	Frame  []byte    // Pre-encoded FramePatches for fast replay
	SentAt time.Time // When the frame was sent
}

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

type PrefetchCacheEntry struct {
	// Tree is the rendered VNode tree
	Tree *vdom.VNode

	// CreatedAt is when this entry was created
	CreatedAt time.Time

	// ExpiresAt is when this entry expires
	ExpiresAt time.Time
}

type PrefetchConfig struct {
	// TTL is how long a prefetched result is valid.
	// Default: 30 seconds
	TTL time.Duration

	// MaxEntries is the maximum number of cached entries per session.
	// Uses LRU eviction when exceeded.
	// Default: 10
	MaxEntries int

	// Timeout is the maximum time to wait for a prefetch to complete.
	// If exceeded, the prefetch is aborted and result is not cached.
	// Default: 100ms
	Timeout time.Duration

	// RateLimit is the maximum prefetch requests per second per session.
	// Excess requests are silently dropped.
	// Default: 5
	RateLimit float64

	// SessionConcurrency is the max simultaneous prefetch evaluations per session.
	// Default: 2
	SessionConcurrency int

	// GlobalConcurrency is the max simultaneous prefetch evaluations globally.
	// Default: 50
	GlobalConcurrency int
}

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

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

type PrimitiveInfo struct {
	StableID     string
	DebugName    string
	AnchorKey    string
	Kind         string
	Class        string
	Persisted    bool
	InstancePath string
	Primitive    any
}

type ProtocolError struct {
	SessionID string
	Op        string
	Message   string
}

type RenderMode int

type ResizeEvent struct {
	Width  int
	Height int
}

type RouteMatch interface {
	// GetParams returns the extracted route parameters.
	GetParams() map[string]string

	// GetPageHandler returns the page handler, if any.
	GetPageHandler() PageHandler

	// GetLayoutHandlers returns the layout handlers in order (root to leaf).
	GetLayoutHandlers() []LayoutHandler

	// GetMiddleware returns the middleware chain.
	GetMiddleware() []RouteMiddleware
}

type RouteMiddleware interface {
	Handle(ctx Ctx, next func() error) error
}

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

type Router interface {
	// Match finds the handler for a path.
	// Returns the match result and whether a match was found.
	Match(method, path string) (RouteMatch, bool)

	// NotFound returns the 404 handler, if configured.
	NotFound() PageHandler
}

type RuntimeLogEvent string

type RuntimeLogEventSpec struct {
	Event         RuntimeLogEvent
	Level         slog.Level
	Message       string
	RequiredAttrs []string
	Description   string
}

type SchemaError struct {
	Reason        string
	Message       string
	Reasons       []string
	IsCold        bool
	SchemaHash    string
	SchemaVersion uint16
}

type ScrollEvent struct {
	ScrollTop  int
	ScrollLeft int
}

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

type ServerConfig struct {
	// Address is the address to listen on (e.g., ":8080" or "localhost:3000").
	// Default: ":8080".
	Address string

	// ReadBufferSize is the WebSocket read buffer size.
	// Default: 4096.
	ReadBufferSize int

	// WriteBufferSize is the WebSocket write buffer size.
	// Default: 4096.
	WriteBufferSize int

	// CheckOrigin is called to validate the request origin.
	// Default: same-origin validation.
	// For allowlist policies, configure via WithAllowedOrigins or AllowedOriginsCheck.
	CheckOrigin func(r *http.Request) bool

	// OriginPolicy describes how WebSocket origin checks are configured.
	// Used for validation and guardrails in production.
	OriginPolicy OriginPolicyMode

	// AllowedOrigins lists domains allowed for WebSocket connections.
	// Entries must be valid origins (scheme + host + optional port) with no path,
	// query, or fragment. Origin matching is normalized by scheme + lowercase host
	// + effective port (default ports may be omitted or explicit).
	// Used for validation when OriginPolicy is OriginPolicyAllowedOrigins.
	AllowedOrigins []string

	// AllowSameOrigin enables same-origin validation.
	// Used for validation when OriginPolicy is OriginPolicySameOrigin.
	AllowSameOrigin bool

	// AllowCustomOriginPolicy explicitly permits custom origin checks in production.
	AllowCustomOriginPolicy bool

	// SessionConfig is the configuration for individual sessions.
	// Default: DefaultSessionConfig().
	SessionConfig *SessionConfig
	// SessionLimits overrides the default session limits when non-nil.
	// Values in this struct are authoritative, including zero values
	// (for example, MaxSessions=0 means unlimited).
	SessionLimits *SessionLimits

	// ShutdownTimeout is the maximum time to wait for graceful shutdown.
	// Default: 30 seconds.
	ShutdownTimeout time.Duration

	// ReadHeaderTimeout is the maximum time to read request headers.
	// Default: 5 seconds.
	ReadHeaderTimeout time.Duration

	// ReadTimeout is the maximum time to read the entire request.
	// Default: 30 seconds.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum time to write the response.
	// Default: 30 seconds.
	WriteTimeout time.Duration

	// IdleTimeout is the maximum time to wait for the next request
	// when keep-alives are enabled.
	// Default: 60 seconds.
	IdleTimeout time.Duration

	// LivenessPath is the built-in liveness endpoint path.
	// Default: /_vango/health/live.
	LivenessPath string

	// ReadinessPath is the built-in readiness endpoint path.
	// Default: /_vango/health/ready.
	ReadinessPath string

	// LivenessCheck optionally gates the liveness endpoint.
	// Return nil for live; return an error to respond with 503.
	LivenessCheck HealthCheck

	// ReadinessCheck optionally gates the readiness endpoint.
	// Return nil for ready; return an error to respond with 503.
	ReadinessCheck HealthCheck

	// MaxSessions is a legacy convenience override for the global session cap.
	// Used only when SessionLimits is nil.
	// Values > 0 override DefaultSessionLimits().MaxSessions.
	// Values <= 0 leave the default effective cap unchanged.
	// Default: 0 (no legacy override).
	MaxSessions int

	// MaxMemoryPerSession is the approximate memory limit per session.
	// Sessions exceeding this may be evicted under memory pressure.
	// Default: 3MB.
	MaxMemoryPerSession int64

	// MaxConcurrentHandshakes is the maximum number of concurrent WebSocket
	// connections waiting to complete handshake/auth/session admission.
	// Helps bound pre-auth resource usage (FDs/goroutines/memory).
	// 0 means no limit.
	// Default: 1024.
	MaxConcurrentHandshakes int

	// MaxConcurrentHandshakesPerIP is the maximum number of concurrent
	// pre-auth handshakes from a single client IP.
	// Helps prevent per-IP pre-auth socket exhaustion.
	// 0 means no limit.
	// Default: 64.
	MaxConcurrentHandshakesPerIP int

	// CSRFSecret is the secret key for CSRF token generation.
	// If nil and CSRF is enabled in non-DevMode, a random secret is generated
	// at startup (tokens won't survive server restarts).
	// To disable CSRF protection entirely, set CSRFEnabled = false explicitly.
	// For production, prefer a stable 32+ byte secret.
	CSRFSecret []byte

	// CSRFEnabled enables CSRF protection for state-changing HTTP endpoints.
	// Default: true.
	CSRFEnabled bool

	// PreUpgradeCheck runs before upgrading HTTP to WebSocket.
	//
	// Use this as a lightweight pre-upgrade gate (for example:
	// token/header/query/subprotocol checks) to reject unauthenticated
	// or malformed upgrade attempts before a WebSocket socket is allocated.
	//
	// Return nil to allow the upgrade. Return an error to reject with HTTP 403.
	// If the returned error implements `StatusCode() int`, that status code is used
	// when it is in the 4xx/5xx range.
	// Default: nil (disabled).
	PreUpgradeCheck func(r *http.Request) error

	// HostedSurfaceVerifier validates hosted surface identity for SSR/bootstrap
	// requests. When nil, hosted/native surface claims from raw request metadata
	// are ignored by default.
	HostedSurfaceVerifier HostedSurfaceVerifyFunc

	// HostedSurfaceTokenSecret signs short-lived hosted-auth tokens embedded in
	// bootstrap responses for verified hosted surfaces.
	HostedSurfaceTokenSecret []byte

	// AllowedRedirectHosts lists hostnames (and optional ports) allowed for
	// external redirects.
	// Hostname-only entries authorize only the default ports (80 for http, 443
	// for https). Use host:port for non-default ports.
	// When empty, external redirects are rejected.
	// Example: []string{"accounts.example.com", "auth.example.com:8443"}
	AllowedRedirectHosts []string

	// AllowedHosts lists hostnames (and optional ports) that are valid for this
	// server.
	// Hostname-only entries authorize only the request scheme's default port
	// (80 for insecure requests, 443 for secure requests). Use host:port for
	// non-default ports.
	// Used outside DevMode to validate the Host header before app request
	// routing, and in WebSocketURL() to prevent Host header poisoning. If empty,
	// WebSocketURL() returns an empty string (fail secure), while request routing
	// remains compatible for deployments that enforce hosts at an external proxy.
	// Example: []string{"myapp.com", "www.myapp.com", "myapp.com:8443"}
	AllowedHosts []string

	// CanonicalHost is the preferred hostname to use when generating URLs.
	// This must be host or host:port. If set and the request Host matches any
	// AllowedHosts entry, this value is used instead. Useful for normalizing
	// "www" vs non-"www" hosts.
	// If empty, the validated request host is used as-is.
	CanonicalHost string

	// PublicRuntimePrefix is the public mount prefix used when generating
	// runtime endpoint URLs for the thin client bootstrap.
	//
	// Examples:
	//   ""     -> /_vango/live and /_vango/client.js
	//   "/app" -> /app/_vango/live and /app/_vango/client.js
	//
	// This affects generated public URLs only. Internal handler routing remains
	// rooted at /_vango/* and any external router or reverse proxy is responsible
	// for applying or stripping the configured prefix.
	PublicRuntimePrefix string

	// CleanupInterval is the interval for the session cleanup loop.
	// Default: 30 seconds.
	CleanupInterval time.Duration

	// OnSessionStart is called during WebSocket upgrade, BEFORE the handshake completes.
	// Use this to copy data from the HTTP context (e.g., authenticated user) to the Vango session.
	// This runs SYNCHRONOUSLY before the WebSocket upgrade completes, while r.Context() is still alive.
	// After this callback returns, the HTTP context is dead and cannot be accessed.
	//
	// Example:
	//     OnSessionStart: func(httpCtx context.Context, session *Session) {
	//         if user := myauth.UserFromContext(httpCtx); user != nil {
	//             auth.Set(session, user) // Rehydrate user projection when your app uses it
	//             auth.SetPrincipal(session, auth.Principal{
	//                 ID: user.ID,
	//             }) // Rehydrate principal projection for auth freshness/principal-first flows
	//         }
	//     }
	OnSessionStart func(httpCtx context.Context, session *Session)

	// OnSessionResume is called during WebSocket session resume, BEFORE the handshake completes.
	// Use this to rehydrate session data from the HTTP context (e.g., re-validate and restore user).
	//
	// Unlike OnSessionStart, this is called when resuming an existing session after disconnect.
	// The session's signal state is preserved, but auth data should be revalidated from cookies/headers.
	//
	// Return nil to allow the resume, or an error to reject it.
	// If an error is returned and the session was previously authenticated (auth.WasAuthenticated),
	// the resume is rejected with HandshakeNotAuthorized. If the session was not authenticated,
	// an error is logged but the resume continues as a guest session.
	//
	// IMPORTANT: Simply returning nil is NOT sufficient for security. The hook MUST
	// actually revalidate authentication and rehydrate auth projection via
	// auth.Set() and/or auth.SetPrincipal(), depending on your app.
	// In strict mode without authFunc, resume clears runtime auth projection before
	// this hook runs, so a no-op OnSessionResume is rejected for previously
	// authenticated sessions.
	//
	// Example:
	//     OnSessionResume: func(httpCtx context.Context, session *Session) error {
	//         user, err := myauth.ValidateFromContext(httpCtx)
	//         if err != nil {
	//             return err  // Reject resume if previously authenticated
	//         }
	//         if user != nil {
	//             auth.Set(session, user) // Rehydrate user projection when your app uses it
	//             auth.SetPrincipal(session, auth.Principal{
	//                 ID: user.ID,
	//             }) // Rehydrate principal projection for auth freshness/principal-first flows
	//         }
	//         return nil
	//     }
	OnSessionResume func(httpCtx context.Context, session *Session) error

	// AuthResumePolicy controls how authenticated session resumes are validated.
	//
	// Default: AuthResumePolicyStrict (requires authFunc or OnSessionResume for
	// authenticated sessions to resume).
	//
	// SECURITY: The strict default ensures that leaked session IDs cannot be used
	// to hijack authenticated sessions. If a session ID leaks via XSS, logging,
	// or other vectors, the attacker cannot resume the session without also
	// presenting valid authentication credentials.
	//
	// Set to AuthResumePolicyTrustSessionID only if you understand the security
	// implications and have compensating controls in place.
	AuthResumePolicy AuthResumePolicy

	// AllowTrustSessionIDInProduction acknowledges the security tradeoff of
	// AuthResumePolicyTrustSessionID in non-DevMode.
	//
	// When false (default), non-Dev configs that set TrustSessionID are rejected.
	// TrustSessionID also requires:
	//   - TrustSessionIDRiskAcceptance = TrustSessionIDRiskAcceptanceV1
	//   - ResumeWindow <= 10s
	//   - Session.AuthCheck hardening:
	//     * Check configured
	//     * Interval > 0 and <= ResumeWindow
	//     * FailureMode = FailClosed
	//     * MaxStale <= ResumeWindow
	AllowTrustSessionIDInProduction bool

	// AllowDevModeInNonLocalEnvironment acknowledges the security tradeoff of
	// enabling DevMode alongside non-local / production-like server settings.
	//
	// Localhost development remains allowed without this flag. Non-local binds,
	// non-local host/origin config, trusted proxies, hosted verification, and
	// similar production-like settings require both this flag and
	// DevModeRiskAcceptance in DevMode.
	AllowDevModeInNonLocalEnvironment bool

	// DevModeRiskAcceptance is a required explicit acknowledgement token for
	// DevMode with non-local / production-like config.
	DevModeRiskAcceptance string

	// TrustSessionIDRiskAcceptance is a required explicit acknowledgement token
	// for non-Dev AuthResumePolicyTrustSessionID usage.
	//
	// Set to TrustSessionIDRiskAcceptanceV1 when you intentionally accept the
	// weaker logout/revocation semantics of TrustSessionID.
	// Default: "" (not acknowledged).
	TrustSessionIDRiskAcceptance string

	// AllowUnsafeRawHTMLInProduction acknowledges the security tradeoff of
	// disabling raw-HTML sink sanitization in non-DevMode.
	//
	// When false (default), non-Dev configs that set SessionConfig.URLPolicy.AllowUnsafeRawHTML
	// are rejected.
	//
	// SECURITY: AllowUnsafeRawHTML disables framework sanitization for raw HTML sinks and
	// can enable "gadget injection" of Vango runtime attributes (hooks/islands/WASM) when
	// attacker-controlled HTML reaches a raw sink. Use only for fully trusted HTML with a
	// strong CSP.
	AllowUnsafeRawHTMLInProduction bool

	// UnsafeRawHTMLRiskAcceptance is a required explicit acknowledgement token for
	// non-dev raw HTML sink sanitization bypass.
	UnsafeRawHTMLRiskAcceptance string

	// AllowInsecureModuleOriginsInProduction acknowledges the security tradeoff of
	// allowing insecure http: cross-origin island/WASM module imports on https:
	// pages in non-dev environments.
	AllowInsecureModuleOriginsInProduction bool

	// InsecureModuleOriginsRiskAcceptance is a required explicit acknowledgement
	// token for non-dev insecure cross-origin module origin allowance.
	InsecureModuleOriginsRiskAcceptance string

	// TrustedProxies lists trusted reverse proxy IPs for X-Forwarded-* headers.
	// If set, the server will trust forwarded headers (including X-Forwarded-Proto)
	// from these IPs when determining request security.
	// Default: nil (don't trust proxy headers).
	TrustedProxies []string

	// DebugMode enables extra validation and logging for development.
	// When true:
	// - Session.Set() panics on unserializable types (func, chan)
	// - auth.Get() logs warnings on type mismatches
	// Default: false.
	DebugMode bool

	// DevMode disables security checks for local development.
	// SECURITY: NEVER use in production - this disables:
	// - Origin checking (allows all origins)
	// - CSRF validation
	// - Secure cookie requirements
	// Default: false (secure by default)
	DevMode bool

	// SecureCookies enforces Secure flag on cookies set by the server.
	// Should be true when using HTTPS.
	// Default: true
	SecureCookies bool

	// CookieHTTPOnly sets the HttpOnly flag on cookies set by the server.
	// Prevents JavaScript access to cookies that should not be read by JS.
	// Default: true (except for cookies that explicitly opt out like CSRF).
	CookieHTTPOnly bool

	// SameSiteMode sets the SameSite attribute for cookies.
	// Lax is safe for most use cases and allows OAuth flows.
	// Default: http.SameSiteLaxMode
	SameSiteMode http.SameSite

	// CookieDomain sets the Domain attribute for cookies set by the server.
	// Empty string uses the current domain (most secure).
	// Default: "" (current domain)
	CookieDomain string

	// SessionStore is the persistence backend for sessions.
	// If nil, sessions are only stored in memory (lost on restart).
	// Use session.NewMemoryStore(), session.NewRedisStore(), or session.NewSQLStore().
	// Default: nil (in-memory only).
	SessionStore session.SessionStore

	// GlobalSignalPubSub is the broadcast backend for global signals.
	// When nil, global signals update via eventual consistency only.
	GlobalSignalPubSub corevango.GlobalBroadcastBackend

	// GlobalSignalRefreshInterval controls the periodic anti-entropy refresh
	// cadence for global signals from persistence.
	// When persistence is available, this still runs with pubsub enabled so
	// instances converge after missed broadcasts.
	// 0 disables refresh entirely.
	// Default: 30 seconds.
	GlobalSignalRefreshInterval time.Duration

	// ResumeWindow is how long a detached session remains resumable after disconnect.
	// After this window, the session is permanently expired.
	// 0 disables resumption entirely.
	// Default: 5 minutes.
	ResumeWindow time.Duration

	// MaxDetachedSessions is the maximum number of disconnected sessions to keep in memory.
	// When exceeded, the least recently used sessions are evicted (and persisted if store is configured).
	// Default: 10000.
	MaxDetachedSessions int

	// MaxSessionsPerIP is the maximum number of concurrent sessions from a single IP address.
	// Helps prevent DoS attacks from IP exhaustion.
	// 0 means no limit.
	// Default: 100.
	MaxSessionsPerIP int

	// EvictionPolicy determines how detached sessions are evicted when limits are exceeded.
	// Default: EvictionLRU.
	EvictionPolicy SessionEvictionPolicy

	// EvictOnIPLimit controls whether hitting MaxSessionsPerIP evicts the oldest
	// detached session for that IP instead of rejecting the new session.
	// Default: true when MaxSessionsPerIP > 0.
	EvictOnIPLimit bool

	// PersistInterval is how often to persist dirty sessions to the store.
	// Set to 0 to only persist on disconnect.
	// Default: 30 seconds.
	PersistInterval time.Duration

	// AssetResolver is the resolver for fingerprinted asset paths.
	// When set, ctx.Asset() will use this resolver to map source paths
	// to their fingerprinted versions (e.g., "vango.js" → "vango.a1b2c3d4.min.js").
	//
	// If nil, ctx.Asset() returns paths unchanged.
	//
	// Example:
	//
	//     manifest, _ := vango.LoadAssetManifest("dist/manifest.json")
	//     config.AssetResolver = vango.NewAssetResolver(manifest, "/public/")
	//
	// For development (no fingerprinting):
	//
	//     config.AssetResolver = vango.NewPassthroughResolver("/public/")
	//
	// Default: nil (passthrough behavior).
	AssetResolver assets.Resolver
	// contains filtered or unexported fields
}

type ServerMetrics struct {
	// Sessions
	ActiveSessions int64
	TotalSessions  int64
	SessionCreates int64
	SessionCloses  int64
	PeakSessions   int64

	// Events
	EventsReceived  int64
	EventsProcessed int64
	EventsDropped   int64

	// Patches
	PatchesSent int64
	PatchBytes  int64

	// Network
	BytesSent     int64
	BytesReceived int64

	// Errors
	HandlerPanics int64
	WriteErrors   int64
	ReadErrors    int64
	// Signal write enforcement
	SignalWriteViolationTotal int64

	// Latency (microseconds)
	EventLatencyP50 int64
	EventLatencyP99 int64

	// Memory
	TotalMemory int64

	// Persistence
	PersistWriteRejectedTotal int64
	PersistBytesTotal         int64
	SchemaMismatchTotal       int64

	// Timestamp
	CollectedAt time.Time
}

type Session struct {
	// Identity
	ID string

	CreatedAt  time.Time
	LastActive time.Time // Guarded by metaMu after initialization.

	// Phase 12: Session persistence fields
	IP           string // Client IP address for per-IP limits
	CurrentRoute string // Current page route for restoration. Guarded by metaMu after initialization.

	DetachedAt time.Time // Time when the session detached (per-IP eviction ordering). Guarded by metaMu after initialization.
	// contains filtered or unexported fields
}

type SessionConfig struct {

	// ReadTimeout is the maximum time to wait for a message from the client.
	// Default: 60 seconds.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum time to wait when sending a message.
	// Default: 10 seconds.
	WriteTimeout time.Duration

	// IdleTimeout is the time after which an inactive session is closed.
	// Default: 5 minutes.
	IdleTimeout time.Duration

	// HandshakeTimeout is the maximum time for the initial handshake.
	// Default: 5 seconds.
	HandshakeTimeout time.Duration

	// InitialMountResourcePreload keeps the first live session tree aligned with the
	// SSR HTML by preloading setup.Resource/setup.ResourceKeyed reads during
	// Session.MountRoot.
	//
	// This mirrors SSR resource-preload behavior for the initial websocket mount so
	// the browser's SSR DOM and the session's currentTree start from the same data
	// state. When disabled, the initial live tree mounts cold and resources resolve
	// later through the normal effect/dispatch path.
	//
	// Default: true.
	InitialMountResourcePreload bool

	// InitialMountResourceTimeout bounds how long initial live-mount resource
	// preloading waits before falling back to the component's loading shell.
	//
	// When > 0, initial mount preload work uses a timeout child context derived from
	// the session stdlib context. Eligible resources are started before waiting and
	// share that one timeout budget. If the timeout expires, the mount keeps the
	// resource in Loading and the normal post-commit resource effect retries on the
	// live session loop.
	//
	// 0 disables waiting, but resources still start opportunistically during the
	// initial live mount.
	//
	// Default: 300ms.
	InitialMountResourceTimeout time.Duration

	// HeartbeatInterval is the time between heartbeat pings.
	// Default: 30 seconds.
	HeartbeatInterval time.Duration

	// MaxMessageSize is the maximum size of an incoming WebSocket message.
	// Default: 64KB.
	MaxMessageSize int64

	// MaxHandshakePathBytes limits the size of the `?path=` query parameter
	// used during the WebSocket handshake (decoded bytes, includes query string).
	// 0 means no limit (not recommended).
	// Default: 8KB.
	MaxHandshakePathBytes int

	// MaxPatchHistory is the number of recent patches to keep for resync.
	// Default: 100.
	MaxPatchHistory int

	// MaxEventQueue is the maximum number of queued client events per session.
	// When full, new events are dropped and QueueEvent returns ErrEventQueueFull.
	// Default: 256.
	MaxEventQueue int

	// MaxDispatchQueue is the maximum number of queued dispatch callbacks per session.
	//
	// Dispatch callbacks are framework-critical (they apply Resource/Action results and
	// other off-loop work back onto the session loop). They MUST NOT be silently dropped.
	// If the dispatch queue is full and a callback cannot be enqueued, the session will
	// self-heal (fatal error + reload).
	//
	// If zero, it defaults to MaxEventQueue for backwards compatibility.
	// Default: 2048.
	MaxDispatchQueue int

	// MaxDetachedSessions limits the number of detached sessions retained in memory.
	// 0 means unlimited, which is not recommended for production.
	// Default: 10000.
	MaxDetachedSessions int

	// EvictionPolicy controls which detached session is evicted when MaxDetachedSessions is reached.
	// Default: EvictionLRU.
	EvictionPolicy SessionEvictionPolicy

	// EnableCompression enables WebSocket compression.
	// Default: true.
	EnableCompression bool

	// EnableOptimistic enables optimistic updates on the client.
	// Default: true.
	EnableOptimistic bool

	// DebugMode enables extra validation and logging for development.
	// When true:
	// - Session.Set() panics on unserializable types (func, chan)
	// - auth.Get() logs warnings on type mismatches
	// Default: false.
	DebugMode bool

	// URLPolicy controls scheme allowlists for URL-bearing attributes.
	// If zero-valued, defaults are used.
	URLPolicy vdom.URLPolicy

	// StormBudget configures rate limits for effect primitives to prevent
	// amplification bugs (e.g., effect triggers resource refetch triggers effect).
	// See SPEC_ADDENDUM.md §A.4.
	StormBudget *StormBudgetConfig

	// AuthCheck configures authentication freshness checks for the session.
	// When nil, no passive or active auth checks are performed.
	AuthCheck *AuthCheckConfig

	// StateBudget configures persisted state size limits.
	StateBudget *corevango.StateBudgetConfig

	// Observability controls optional logging for mutations.
	Observability corevango.ObservabilityConfig

	// Metrics is the sink for runtime metric emissions.
	// Nil disables metric emission (safe default).
	Metrics corevango.MetricsSink

	// EventMiddleware runs for every WebSocket event before handler execution.
	// Use this for tracing, logging, or rate limiting (e.g., middleware.OpenTelemetry()).
	EventMiddleware []RouteMiddleware

	// PersistenceSecret signs persisted blobs.
	// This includes session persistence and global-signal blobs when
	// global persistence/pubsub paths are enabled.
	// Must be 32+ bytes of cryptographically random data.
	PersistenceSecret []byte

	// PersistenceSecretPrevious allows secret rotation.
	// If set, blobs signed with this secret are accepted on resume.
	PersistenceSecretPrevious []byte

	// MaxBlobAgeMs sets the maximum age in milliseconds for persisted session resume blobs.
	// Blobs older than this are rejected during resume, triggering a fresh session.
	// This applies to session resume only (not global signals).
	// This helps prevent replay attacks with stale session data.
	// 0 means no limit (default).
	MaxBlobAgeMs int64

	// HookEventValidator validates client hook event payloads.
	// Return an error to reject the event.
	// In production, startup warnings are emitted when this is unset.
	HookEventValidator corevango.HookEventValidator

	// DOMEventRateLimit applies per-session rate limiting to standard DOM events
	// (click/input/scroll/etc., including navigation).
	// RatePerSecond <= 0 disables rate limiting.
	DOMEventRateLimit *corevango.EventRateLimitConfig

	// HookEventRateLimit applies per-session rate limiting to hook events.
	// RatePerSecond <= 0 disables rate limiting.
	HookEventRateLimit *corevango.EventRateLimitConfig

	// HookEventMaxPayloadBytes limits JSON size of hook event payloads.
	// 0 means no limit.
	HookEventMaxPayloadBytes int

	// HookEventMaxNameBytes limits hook event name length in bytes.
	// 0 means no limit.
	HookEventMaxNameBytes int

	// EventHIDMaxBytes limits inbound event HID length in bytes.
	// Applies to all event types at ingress and session-loop fallback.
	// 0 means no limit.
	EventHIDMaxBytes int

	// IslandMessageValidator validates island message payloads.
	// Return an error to reject the message.
	// In production, startup warnings are emitted when this is unset.
	IslandMessageValidator corevango.IslandMessageValidator

	// IslandEventRateLimit applies per-session rate limiting to island messages.
	// RatePerSecond <= 0 disables rate limiting.
	IslandEventRateLimit *corevango.EventRateLimitConfig

	// IslandEventMaxPayloadBytes limits JSON size of island message payloads.
	// 0 means no limit.
	IslandEventMaxPayloadBytes int

	// IslandEventMaxWrapperBytes limits JSON size of island wrapper payloads.
	// Wrapper payloads are the custom event JSON object containing `id` + `payload`.
	// 0 means no limit.
	IslandEventMaxWrapperBytes int

	// IslandEventMaxJSONDepth limits maximum JSON nesting depth for island
	// wrapper and payload JSON structures.
	// 0 means no limit.
	IslandEventMaxJSONDepth int

	// IslandEventMaxIDBytes limits island identifier length in bytes.
	// 0 means no limit.
	IslandEventMaxIDBytes int

	// WasmMessageValidator validates WASM message payloads.
	// Return an error to reject the message.
	// In production, startup warnings are emitted when this is unset.
	WasmMessageValidator corevango.WasmMessageValidator

	// WasmEventRateLimit applies per-session rate limiting to WASM messages.
	// RatePerSecond <= 0 disables rate limiting.
	WasmEventRateLimit *corevango.EventRateLimitConfig

	// WasmEventMaxPayloadBytes limits JSON size of WASM message payloads.
	// 0 means no limit.
	WasmEventMaxPayloadBytes int

	// WasmEventMaxWrapperBytes limits JSON size of WASM wrapper payloads.
	// Wrapper payloads are the custom event JSON object containing `id` + `payload`.
	// 0 means no limit.
	WasmEventMaxWrapperBytes int

	// WasmEventMaxJSONDepth limits maximum JSON nesting depth for WASM
	// wrapper and payload JSON structures.
	// 0 means no limit.
	WasmEventMaxJSONDepth int

	// WasmEventMaxIDBytes limits WASM identifier length in bytes.
	// 0 means no limit.
	WasmEventMaxIDBytes int

	// AllowRawHTMLInEventPayloads permits raw HTML or executable strings in
	// hook/island/WASM payloads. Default: false.
	// NOTE: Vango's unsafe-payload check is a heuristic substring filter,
	// not a sanitizer. Always validate and/or sanitize untrusted payloads.
	AllowRawHTMLInEventPayloads bool

	// AllowHeuristicEventPayloadsInProduction keeps hook/island/WASM payload
	// handling in heuristic-only mode in non-dev environments.
	//
	// This is a break-glass escape hatch. When false (default), non-dev sessions
	// reject reachable hook/island/WASM sinks unless they are covered by a
	// session-level validator or an exact-sink validated helper.
	AllowHeuristicEventPayloadsInProduction bool

	// HeuristicEventPayloadRiskAcceptance is a required explicit acknowledgement
	// token for non-dev heuristic-only hook/island/WASM payload handling.
	//
	// Set to HeuristicEventPayloadRiskAcceptanceV1 when you intentionally accept
	// heuristic-only event payload screening for reachable sinks in non-dev mode.
	HeuristicEventPayloadRiskAcceptance string

	// ResyncRateLimitConfig applies per-session rate limiting to resync requests.
	// Resync requests can trigger expensive full HTML renders (SendResyncFull) when
	// the patch history is exhausted, making them a DoS amplification vector.
	//
	// A malicious client can repeatedly send resync requests to:
	//   - Consume CPU (rendering full component tree to HTML)
	//   - Consume bandwidth (sending large HTML payloads)
	//   - Amplify per-session cost across many concurrent sessions
	//
	// Default: 2/sec with burst 5 (conservative, resync should be rare).
	// RatePerSecond <= 0 disables rate limiting (NOT RECOMMENDED in production).
	ResyncRateLimitConfig *corevango.EventRateLimitConfig
}

type SessionError struct {
	SessionID string
	Op        string // Operation that failed
	Err       error  // Underlying error
}

type SessionEvictionPolicy int

type SessionLimits struct {
	// MaxSessions is the maximum number of concurrent sessions.
	MaxSessions int

	// MaxMemoryPerSession is the approximate memory limit per session.
	MaxMemoryPerSession int64

	// MaxTotalMemory is the total memory budget for all sessions.
	// If exceeded, least recently used sessions are evicted.
	MaxTotalMemory int64
}

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

type SessionManagerOptions struct {
	// SessionStore is the persistence backend for sessions.
	SessionStore session.SessionStore

	// ResumeWindow is how long detached sessions remain resumable.
	// nil means use the default (5 minutes).
	// 0 disables resumption entirely.
	ResumeWindow *time.Duration

	// MaxDetachedSessions is the maximum detached sessions before LRU eviction.
	MaxDetachedSessions int

	// MaxSessionsPerIP is the maximum sessions per IP address.
	MaxSessionsPerIP int

	// EvictOnIPLimit controls whether to evict the oldest detached session
	// for a full IP bucket instead of rejecting new sessions.
	EvictOnIPLimit bool

	// EvictionPolicy determines how detached sessions are evicted when limits are exceeded.
	EvictionPolicy SessionEvictionPolicy

	// PersistInterval is how often to persist dirty sessions.
	PersistInterval time.Duration

	// GlobalSignalPubSub is the broadcast backend for global signals.
	GlobalSignalPubSub vango.GlobalBroadcastBackend

	// GlobalSignalRefreshInterval controls the periodic anti-entropy refresh
	// cadence from persistence. When persistence is available, this still runs
	// with pubsub enabled to heal missed broadcasts.
	GlobalSignalRefreshInterval time.Duration

	// RedirectAllowlist is the normalized allowlist for external redirects.
	// When nil or empty, external redirects are rejected.
	RedirectAllowlist map[allowedAuthority]struct{}
}

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